Skip to content

Commit f5f93a3

Browse files
alcaeusalcaeus
authored
PHPORM-83: Document release process (mongodb#2604)
* PHPORM-83: Document release process * Update branch-alias in composer.json * Use correct identifier for laravel versions * Apply review feedback
1 parent 9bc8999 commit f5f93a3

File tree

3 files changed

+199
-1
lines changed

3 files changed

+199
-1
lines changed

‎CONTRIBUTING.md

+6-1
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

+190
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
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 "laravel-*.x" fix version to see if it contains any
28+
issues that are resolved as "Fixed" and should be included in this release
29+
version.
30+
31+
Update the version's release date and status from the
32+
[Manage Versions](https://jira.mongodb.org/plugins/servlet/project-config/PHPORM/versions)
33+
page.
34+
35+
## Update version info
36+
37+
This uses [semantic versioning](https://semver.org/). Do not break
38+
backwards compatibility in a non-major release or your users will kill you.
39+
40+
Before proceeding, ensure that the `master` branch is up-to-date with all code
41+
changes in this maintenance branch. This is important because we will later
42+
merge the ensuing release commits up to master with `--strategy=ours`, which
43+
will ignore changes from the merged commits.
44+
45+
## Update composer.json
46+
47+
This is especially important before releasing a new minor version.
48+
49+
Ensure that the extension and PHP library requirements, as well as the branch
50+
alias in `composer.json` are correct for the version being released. For
51+
example, the branch alias for the 4.1.0 release in the `master` branch should
52+
be `4.1.x-dev`.
53+
54+
Commit and push any changes:
55+
56+
```console
57+
$ git commit -m "Update composer.json X.Y.Z" composer.json
58+
$ git push mongodb
59+
```
60+
61+
## Tag the release
62+
63+
Create a tag for the release and push:
64+
65+
```console
66+
$ git tag -a -m "Release X.Y.Z" X.Y.Z
67+
$ git push mongodb --tags
68+
```
69+
70+
## Branch management
71+
72+
# Creating a maintenance branch and updating master branch alias
73+
74+
After releasing a new major or minor version (e.g. 4.0.0), a maintenance branch
75+
(e.g. v4.0) should be created. Any development towards a patch release (e.g.
76+
4.0.1) would then be done within that branch and any development for the next
77+
major or minor release can continue in master.
78+
79+
After creating a maintenance branch, the `extra.branch-alias.dev-master` field
80+
in the master branch's `composer.json` file should be updated. For example,
81+
after branching v4.0, `composer.json` in the master branch may still read:
82+
83+
```
84+
"branch-alias": {
85+
"dev-master": "4.0.x-dev"
86+
}
87+
```
88+
89+
The above would be changed to:
90+
91+
```
92+
"branch-alias": {
93+
"dev-master": "4.1.x-dev"
94+
}
95+
```
96+
97+
Commit this change:
98+
99+
```console
100+
$ git commit -m "Master is now 4.1-dev" composer.json
101+
```
102+
103+
### After releasing a new minor version
104+
105+
After a new minor version is released (i.e. `master` was tagged), a maintenance
106+
branch should be created for future patch releases:
107+
108+
```console
109+
$ git checkout -b vX.Y
110+
$ git push mongodb vX.Y
111+
```
112+
113+
Update the master branch alias in `composer.json`:
114+
115+
```diff
116+
"extra": {
117+
"branch-alias": {
118+
- "dev-master": "4.0.x-dev"
119+
+ "dev-master": "4.1.x-dev"
120+
}
121+
},
122+
```
123+
124+
Commit and push this change:
125+
126+
```console
127+
$ git commit -m "Master is now X.Y-dev" composer.json
128+
$ git push mongodb
129+
```
130+
131+
### After releasing a patch version
132+
133+
If this was a patch release, the maintenance branch must be merged up to master:
134+
135+
```console
136+
$ git checkout master
137+
$ git pull mongodb master
138+
$ git merge vX.Y --strategy=ours
139+
$ git push mongodb
140+
```
141+
142+
The `--strategy=ours` option ensures that all changes from the merged commits
143+
will be ignored. This is OK because we previously ensured that the `master`
144+
branch was up-to-date with all code changes in this maintenance branch before
145+
tagging.
146+
147+
148+
## Publish release notes
149+
150+
The following template should be used for creating GitHub release notes via
151+
[this form](https://github.com/mongodb/laravel-mongodb/releases/new).
152+
153+
```markdown
154+
The PHP team is happy to announce that version X.Y.Z of the MongoDB integration for Laravel is now available.
155+
156+
**Release Highlights**
157+
158+
<one or more paragraphs describing important changes in this release>
159+
160+
A complete list of resolved issues in this release may be found in [JIRA]($JIRA_URL).
161+
162+
**Documentation**
163+
164+
Documentation for this library may be found in the [Readme](https://github.com/mongodb/laravel-mongodb/blob/$VERSION/README.md).
165+
166+
**Installation**
167+
168+
This library may be installed or upgraded with:
169+
170+
composer require mongodb/laravel-mongodb:X.Y.Z
171+
172+
Installation instructions for the `mongodb` extension may be found in the [PHP.net documentation](https://php.net/manual/en/mongodb.installation.php).
173+
```
174+
175+
The URL for the list of resolved JIRA issues will need to be updated with each
176+
release. You may obtain the list from
177+
[this form](https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=22488).
178+
179+
If commits from community contributors were included in this release, append the
180+
following section:
181+
182+
```markdown
183+
**Thanks**
184+
185+
Thanks for our community contributors for this release:
186+
187+
* [$CONTRIBUTOR_NAME](https://github.com/$GITHUB_USERNAME)
188+
```
189+
190+
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.

‎composer.json

+3
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,9 @@
5050
}
5151
},
5252
"extra": {
53+
"branch-alias": {
54+
"dev-master": "4.0.x-dev"
55+
},
5356
"laravel": {
5457
"providers": [
5558
"MongoDB\\Laravel\\MongodbServiceProvider",

0 commit comments

Comments
 (0)