Skip to content

Commit b09146a

Browse files
alcaeusalcaeus
committed
PHPORM-83: Document release process
1 parent 9bc8999 commit b09146a

File tree

2 files changed

+195
-1
lines changed

2 files changed

+195
-1
lines changed

‎CONTRIBUTING.md

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,4 +52,9 @@ If the project maintainer has any additional requirements, you will find them li
5252

5353
- **Send coherent history** - Make sure each individual commit in your pull request is meaningful. If you had to make multiple intermediate commits while developing, please [squash them](https://www.git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages) before submitting.
5454

55-
**Happy coding**!
55+
**Happy coding**!
56+
57+
## Releasing
58+
59+
The releases are created by the maintainers of the library. The process is documented in
60+
the [RELEASING.md](RELEASING.md) file.

‎RELEASING.md

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# Releasing
2+
3+
The following steps outline the release process for both new minor versions (e.g.
4+
releasing the `master` branch as X.Y.0) and patch versions (e.g. releasing the
5+
`vX.Y` branch as X.Y.Z).
6+
7+
The command examples below assume that the canonical "mongodb" repository has
8+
the remote name "mongodb". You may need to adjust these commands if you've given
9+
the remote another name (e.g. "upstream"). The "origin" remote name was not used
10+
as it likely refers to your personal fork.
11+
12+
It helps to keep your own fork in sync with the "mongodb" repository (i.e. any
13+
branches and tags on the main repository should also exist in your fork). This
14+
is left as an exercise to the reader.
15+
16+
## Ensure PHP version compatibility
17+
18+
Ensure that the test suite completes on supported versions of PHP.
19+
20+
## Transition JIRA issues and version
21+
22+
All issues associated with the release version should be in the "Closed" state
23+
and have a resolution of "Fixed". Issues with other resolutions (e.g.
24+
"Duplicate", "Works as Designed") should be removed from the release version so
25+
that they do not appear in the release notes.
26+
27+
Check the corresponding ".x" fix version to see if it contains any issues that
28+
are resolved as "Fixed" and should be included in this release version.
29+
30+
Update the version's release date and status from the
31+
[Manage Versions](https://jira.mongodb.org/plugins/servlet/project-config/PHPORM/versions)
32+
page.
33+
34+
## Update version info
35+
36+
This uses [semantic versioning](https://semver.org/). Do not break
37+
backwards compatibility in a non-major release or your users will kill you.
38+
39+
Before proceeding, ensure that the `master` branch is up-to-date with all code
40+
changes in this maintenance branch. This is important because we will later
41+
merge the ensuing release commits up to master with `--strategy=ours`, which
42+
will ignore changes from the merged commits.
43+
44+
## Update composer.json
45+
46+
This is especially important before releasing a new minor version.
47+
48+
Ensure that the extension and PHP library requirements, as well as the branch
49+
alias in `composer.json` are correct for the version being released. For
50+
example, the branch alias for the 4.1.0 release in the `master` branch should
51+
be `4.1.x-dev`.
52+
53+
Commit and push any changes:
54+
55+
```console
56+
$ git commit -m "Update composer.json X.Y.Z" composer.json
57+
$ git push mongodb
58+
```
59+
60+
## Tag the release
61+
62+
Create a tag for the release and push:
63+
64+
```console
65+
$ git tag -a -m "Release X.Y.Z" X.Y.Z
66+
$ git push mongodb --tags
67+
```
68+
69+
## Branch management
70+
71+
# Creating a maintenance branch and updating master branch alias
72+
73+
After releasing a new major or minor version (e.g. 4.0.0), a maintenance branch
74+
(e.g. v4.0) should be created. Any development towards a patch release (e.g.
75+
4.0.1) would then be done within that branch and any development for the next
76+
major or minor release can continue in master.
77+
78+
After creating a maintenance branch, the `extra.branch-alias.dev-master` field
79+
in the master branch's `composer.json` file should be updated. For example,
80+
after branching v4.0, `composer.json` in the master branch may still read:
81+
82+
```
83+
"branch-alias": {
84+
"dev-master": "4.0.x-dev"
85+
}
86+
```
87+
88+
The above would be changed to:
89+
90+
```
91+
"branch-alias": {
92+
"dev-master": "4.1.x-dev"
93+
}
94+
```
95+
96+
Commit this change:
97+
98+
```console
99+
$ git commit -m "Master is now 4.1-dev" composer.json
100+
```
101+
102+
### After releasing a new minor version
103+
104+
After a new minor version is released (i.e. `master` was tagged), a maintenance
105+
branch should be created for future patch releases:
106+
107+
```console
108+
$ git checkout -b vX.Y
109+
$ git push mongodb vX.Y
110+
```
111+
112+
Update the master branch alias in `composer.json`:
113+
114+
```diff
115+
"extra": {
116+
"branch-alias": {
117+
- "dev-master": "4.0.x-dev"
118+
+ "dev-master": "4.1.x-dev"
119+
}
120+
},
121+
```
122+
123+
Commit and push this change:
124+
125+
```console
126+
$ git commit -m "Master is now X.Y-dev" composer.json
127+
$ git push mongodb
128+
```
129+
130+
### After releasing a patch version
131+
132+
If this was a patch release, the maintenance branch must be merged up to master:
133+
134+
```console
135+
$ git checkout master
136+
$ git pull mongodb master
137+
$ git merge vX.Y --strategy=ours
138+
$ git push mongodb
139+
```
140+
141+
The `--strategy=ours` option ensures that all changes from the merged commits
142+
will be ignored. This is OK because we previously ensured that the `master`
143+
branch was up-to-date with all code changes in this maintenance branch before
144+
tagging.
145+
146+
147+
## Publish release notes
148+
149+
The following template should be used for creating GitHub release notes via
150+
[this form](https://github.com/mongodb/laravel-mongodb/releases/new).
151+
152+
```markdown
153+
The PHP team is happy to announce that version X.Y.Z of the MongoDB integration for Laravel is now available.
154+
155+
**Release Highlights**
156+
157+
<one or more paragraphs describing important changes in this release>
158+
159+
A complete list of resolved issues in this release may be found in [JIRA]($JIRA_URL).
160+
161+
**Documentation**
162+
163+
Documentation for this library may be found in the [Readme](https://github.com/mongodb/laravel-mongodb/blob/$VERSION/README.md).
164+
165+
**Installation**
166+
167+
This library may be installed or upgraded with:
168+
169+
composer require mongodb/laravel-mongodb:X.Y.Z
170+
171+
Installation instructions for the `mongodb` extension may be found in the [PHP.net documentation](https://php.net/manual/en/mongodb.installation.php).
172+
```
173+
174+
The URL for the list of resolved JIRA issues will need to be updated with each
175+
release. You may obtain the list from
176+
[this form](https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=22488).
177+
178+
If commits from community contributors were included in this release, append the
179+
following section:
180+
181+
```markdown
182+
**Thanks**
183+
184+
Thanks for our community contributors for this release:
185+
186+
* [$CONTRIBUTOR_NAME](https://github.com/$GITHUB_USERNAME)
187+
```
188+
189+
Release announcements should also be posted in the [MongoDB Product & Driver Announcements: Driver Releases](https://mongodb.com/community/forums/tags/c/announcements/driver-releases/110/php) forum and shared on Twitter.

0 commit comments

Comments
 (0)