You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The patch flow is for making **patch releases**. As per semantic versioning,
40
-
patch releases are for simple changes, eg: typo fixes, patch dependency updates,
41
-
and simple/low-risk bug fixes. Every other type of change is made via the
42
-
non-patch flow.
43
32
44
-
### Branch terminology
33
+
##How to publish a release
45
34
46
-
"Master branch"
35
+
Notes:
47
36
48
-
- There is a branch in git used for the current major version of Express, named
49
-
`master`.
50
-
- This branch contains the completed commits for the next patch release of the
51
-
current major version.
52
-
- Releases for the current major version are published from this branch.
37
+
- Version strings are listed below as "vx.y.z" or "x.y.z". Substitute for the release version.
38
+
- Examples will use the fictional release version 11.22.33.
53
39
54
-
"Version branch"
40
+
**Key considerations for security releases**
55
41
56
-
- For any given major version of Express (current, previous or next) there is
57
-
a branch in git for that release named `<major-version>.x` (eg: `4.x`).
58
-
- This branch points to the commit of the latest tag for the given major version.
42
+
When preparing a security release, follow the instruction in [security-release.md] and not this guide.
59
43
60
-
"Release branch"
44
+
Security releases are a special case and should be handled with care. If you are
45
+
preparing a security release, you should follow the security steps in the details
46
+
sections. It is extremely important to avoid disclosing security vulnerabilities
47
+
before the release is available to the public, to avoid putting users at risk.
61
48
62
-
- For any given major version of Express, there is a branch used for publishing
63
-
releases.
64
-
- For the current major version of Express, the release branch is the
65
-
"Master branch" named `master`.
66
-
- For all other major versions of Express, the release branch is the
67
-
"Version branch" named `<major-version>.x`.
68
49
69
-
"Proposal branch"
50
+
### 0. Pre-release steps
70
51
71
-
- A branch in git representing a proposed new release of Express. This can be a
72
-
minor or major release, named `<major-version>.0` for a major release,
73
-
`<major-version>.<minor-version>` for a minor release.
74
-
- A tracking pull request should exist to document the proposed release,
75
-
targeted at the appropriate release branch. Prior to opening the tracking
76
-
pull request the content of the release may have be discussed in an issue.
77
-
- This branch contains the commits accepted so far that implement the proposal
78
-
in the tracking pull request.
52
+
**Define the scope**
53
+
Before preparing a Express.js release, you should know:
54
+
- the potential proposed changes (eg: bug fixes, new features, etc)
55
+
- the type of release: patch, minor or major
56
+
- the version number (according to semantic versioning - http://semver.org)
57
+
- the release date expected (when the release will be available in npm).
79
58
80
-
### Patch flow
59
+
**Choosing a good date**
81
60
82
-
In the patch flow, simple changes are committed to the release branch which
83
-
acts as an ever-present branch for the next patch release of the associated
84
-
major version of Express.
61
+
Please avoid releasing on weekends or holidays as it may be difficult to get help if something goes wrong and also to avoid the need to work for the users that will need to update their applications.
85
62
86
-
The release branch is usually kept in a state where it is ready to release.
87
-
Releases are made when sufficient time or change has been made to warrant it.
88
-
This is usually proposed and decided using a github issue.
63
+
**Announce the release**
89
64
90
-
### Non-patch flow
65
+
You should notify the community of your
66
+
intent to release. This can be done by creating a message in the slack channel
67
+
`#express`. This is to ensure that the community is aware of the release and
68
+
can provide feedback if necessary.
91
69
92
-
In the non-patch flow, changes are committed to a temporary proposal branch
93
-
created specifically for that release proposal. The branch is based on the
94
-
most recent release of the major version of Express that the release targets.
70
+
**Prepare the environment**
95
71
96
-
Releases are made when all the changes on a proposal branch are complete and
97
-
approved. This is done by merging the proposal branch into the release branch
98
-
(using a fast-forward merge), tagging it with the new version number and
99
-
publishing the release package to npmjs.com.
72
+
It is expected that you will have a clean environment to prepare the release
73
+
and you should have a personal fork of the `expressjs/express` repository to push the
74
+
release branch to it.
100
75
101
-
### Flow
102
76
103
-
Below is a detailed description of the steps to publish a release.
77
+
### 1. Checkout the major branch and create the release proposal branch
104
78
105
-
#### Step 1. Check the release is ready to publish
79
+
Checkout the major branch locally.
106
80
107
-
Check any relevant information to ensure the release is ready, eg: any
108
-
milestone, label, issue or tracking pull request for the release. The release
109
-
is ready when all proposed code, tests and documentation updates are complete
110
-
(either merged, closed or re-targeted to another release).
81
+
```bash
82
+
git remote update
83
+
git checkout 11.x
84
+
git reset --hard upstream/11.x
85
+
```
111
86
112
-
#### Step 2. (Non-patch flow only) Merge the proposal branch into the release branch
87
+
Create a new branch for the release proposal and push it.
88
+
89
+
```bash
90
+
git checkout -b 11.22.33-proposal
91
+
git push origin 11.22.33-proposal
92
+
git push upstream 11.22.33-proposal
93
+
```
113
94
114
-
In the patch flow: skip this step.
115
95
116
-
In the non-patch flow:
117
-
```sh
118
-
$ git checkout <release-branch>
119
-
$ git merge --ff-only <proposal-branch>
96
+
### 2. Cherry pick and backport the changes
97
+
98
+
Cherry pick and backport the changes to the `11.22.33-proposal` branch
99
+
that you want to include in the release and then push the changes
100
+
101
+
```bash
102
+
git cherry-pick -x <commit-hash>
103
+
# repeat for each commit that you want to include in the release
104
+
git push origin 11.22.33-proposal
105
+
git push upstream 11.22.33-proposal
120
106
```
121
107
122
-
<release-branch> - see "Release branch" of "Branches" above.
123
-
<proposal-branch> - see "Proposal branch" of "Non-patch flow" above.
124
108
125
-
**NOTE:** You may need to rebase the proposal branch to allow a fast-forward
126
-
merge. Using a fast-forward merge keeps the history clean as it does
127
-
not introduce merge commits.
109
+
### 3. Update the metadata and the changelog
128
110
129
-
### Step 3. Update the History.md and package.json to the new version number
130
111
131
-
The changes so far for the release should already be documented under the
132
-
"unreleased" section at the top of the History.md file, as per the usual
133
-
development practice. Change "unreleased" to the new release version / date.
134
-
Example diff fragment:
112
+
Update the `History.md` and `package.json` files with the new version and the changes and commit it.
135
113
136
-
```diff
137
-
-unreleased
138
-
-==========
139
-
+4.13.3 / 2015-08-02
140
-
+===================
114
+
115
+
```bash
116
+
git commit -S -m "11.22.33"
141
117
```
142
118
143
-
The version property in the package.json should already contain the version of
144
-
the previous release. Change it to the new release version.
119
+
Push the changes to the release branch
145
120
146
-
Commit these changes together under a single commit with the message set to
147
-
the new release version (eg: `4.13.3`):
121
+
```bash
122
+
git push origin 11.22.33-proposal
123
+
git push upstream 11.22.33-proposal
124
+
```
148
125
149
-
```sh
150
-
$ git checkout <release-branch>
151
-
<..edit files..>
152
-
$ git add History.md package.json
153
-
$ git commit -m '<version-number>'
126
+
### 4. Create a pull request with the release proposal
127
+
128
+
Create a pull request with the release proposal branch and assign the Repo captains and TC Team to review it. You will target the major version branch (eg: `11.x`) from your personal fork.
129
+
130
+
If the CI tests are not passing, please fix the issues and update the pull request with the new changes, you can leave the PR in draft mode until the CI tests are passing.
131
+
132
+
**Important:** if the release has changed you will need to update the files and amend the commit. Add the tag release
133
+
134
+
You can use [this PR](https://github.com/expressjs/express/pull/5505) as a reference
135
+
136
+
### 4. Land the release proposal
137
+
138
+
Once the pull request is approved, you can land it to the major branch (e.g. `11.x`) branch.
139
+
140
+
```bash
141
+
git checkout 11.22.33-proposal
142
+
git rebase 11.x
143
+
git checkout 11.x
144
+
git merge --ff-only 11.22.33-proposal
145
+
git push
154
146
```
155
147
156
-
### Step 4. Identify and tag the release commit with the new release version
148
+
**Important:** a release proposal is approved once the pull request was approved by at least one of the Repo captains or a TC Member and has passed 72h since the PR was opened.
149
+
150
+
Note: The Pull Request will be closed automatically when the release proposal is merged.
157
151
158
-
Create a lightweight tag (rather than an annotated tag) named after the new
159
-
release version (eg: `4.13.3`).
152
+
### 5. Tag the release
160
153
161
-
```sh
162
-
$ git tag <version-number>
154
+
Tag the release from your release branch (e.g. `11.22.33-proposal`) with the same version number
155
+
156
+
```bash
157
+
git checkout 11.22.33-proposal
158
+
git tag 11.22.33 --sign --message "11.22.33"
163
159
```
164
160
165
-
### Step 5. Push the release branch changes and tag to github
161
+
### 6. Push the tag
162
+
163
+
8. Push the tag to the repository, (e.g.`11.22.33`)
164
+
```bash
165
+
git push origin 11.22.33
166
+
git push upstream 11.22.33
167
+
```
168
+
169
+
### 7. Publish the release
170
+
171
+
Create a new release on GitHub using the tag (e.g. https://github.com/UlisesGascon/express/releases/new?tag=11.22.33) use https://github.com/expressjs/express/releases/tag/4.18.3 as an example for title and content format. We can use the `History.md` content has the `Main Changes` section, the other sections are autopopulated when clicking on "Generate Release Notes".
166
172
167
-
The branch and tag should be pushed directly to the main repository
168
-
(https://github.com/expressjs/express).
173
+
### 8. Publish to npm
169
174
170
-
```sh
171
-
$ git push origin <release-branch>
172
-
$ git push origin <version-number>
175
+
This is the most critical step as you won't be able to unpublish the release if something goes wrong. So please double-check everything before publishing.
176
+
177
+
Check the package content:
178
+
179
+
```bash
180
+
npm publish --dry-run
173
181
```
174
182
175
-
### Step 6. Publish to npmjs.com
183
+
When you are ready to publish, run:
184
+
185
+
```bash
186
+
npm publish
187
+
```
176
188
177
-
Ensure your local working copy is completely clean (no extra or changed files).
178
-
You can use `git status` for this purpose.
189
+
### 9. Update the release proposal PR
179
190
180
-
```sh
181
-
$ npm login <npm-username>
182
-
$ npm publish
191
+
Add a comment in the pull request with the confirmation of the release and the link to the release on GitHub and npm, (e.g. https://github.com/expressjs/express/pull/5505#issuecomment-1970980785)
192
+
193
+
### 10. Clean up branches and prepare for the next release
194
+
195
+
Push the release commit to `main` branch and manage the git conflicts if necessary.
196
+
197
+
```bash
198
+
git checkout main
199
+
git reset --hard upstream/main
200
+
git cherry-pick 11.22.33-proposal
201
+
git push origin main
202
+
git push upstream main
203
+
```
204
+
205
+
Once the release is published, you can delete the release proposal branch and the tag from your local and remote repositories.
206
+
207
+
```bash
208
+
git push origin --delete 11.22.33-proposal
209
+
git push upstream --delete 11.22.33-proposal
183
210
```
184
211
185
-
**NOTE:** The version number to publish will be picked up automatically from
186
-
package.json.
212
+
### 11. Announce the release
213
+
214
+
Promote the release on Slack (`#express` channel) and in social media (e.g [4.18.3](https://openjs-foundation.slack.com/archives/C02QB1731FH/p1709208390734159)).
215
+
216
+
### 12. Celebrate it 🎉
217
+
218
+
**Congratulations!** You have successfully released a new version of Express.js. So now it's time to celebrate it _in whatever form you do this..._
0 commit comments