Release-Process.md

   1 # Express Release Process
   2
   3 This document contains the technical aspects of the Express release process. The
   4 intended audience is those who have been authorized by the Express Technical
   5 Committee (TC) to create, promote and sign official release builds for Express,
   6 as npm packages hosted on https://npmjs.com/package/express.
   7
   8 ## Who can make releases?
   9
  10 Release authorization is given by the Express TC. Once authorized, an individual
  11 must have the following access permissions:
  12
  13 ### 1. Github release access
  14
  15 The individual making the release will need to be a member of the
  16 expressjs/express team with Write permission level so they are able to tag the
  17 release commit and push changes to the expressjs/express repository
  18 (see Steps 4 and 5).
  19
  20 ### 2. npmjs.com release access
  21
  22 The individual making the release will need to be made an owner on the
  23 `express` package on npmjs.com so they are able to publish the release
  24 (see Step 6).
  25
  26 ## How to publish a release
  27
  28 Before publishing, the following preconditions should be met:
  29
  30 - A release proposal issue or tracking pull request (see "Proposal branch"
  31   below) will exist documenting:
  32   - the proposed changes
  33   - the type of release: patch, minor or major
  34   - the version number (according to semantic versioning - http://semver.org)
  35 - The proposed changes should be complete.
  36
  37 There are two main release flows: patch and non-patch.
  38
  39 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
  44 ### Branch terminology
  45
  46 "Master branch"
  47
  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.
  53
  54 "Version branch"
  55
  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.
  59
  60 "Release branch"
  61
  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
  69 "Proposal branch"
  70
  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.
  79
  80 ### Patch flow
  81
  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.
  85
  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.
  89
  90 ### Non-patch flow
  91
  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.
  95
  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.
 100
 101 ### Flow
 102
 103 Below is a detailed description of the steps to publish a release.
 104
 105 #### Step 1. Check the release is ready to publish
 106
 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).
 111
 112 #### Step 2. (Non-patch flow only) Merge the proposal branch into the release branch
 113
 114 In the patch flow: skip this step.
 115
 116 In the non-patch flow:
 117 ```sh
 118 $ git checkout <release-branch>
 119 $ git merge --ff-only <proposal-branch>
 120 ```
 121
 122 <release-branch> - see "Release branch" of "Branches" above.
 123 <proposal-branch> - see "Proposal branch" of "Non-patch flow" above.
 124
 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.
 128
 129 ### Step 3. Update the History.md and package.json to the new version number
 130
 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:
 135
 136 ```diff
 137 -unreleased
 138 -==========
 139 +4.13.3 / 2015-08-02
 140 +===================
 141 ```
 142
 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.
 145
 146 Commit these changes together under a single commit with the message set to
 147 the new release version (eg: `4.13.3`):
 148
 149 ```sh
 150 $ git checkout <release-branch>
 151 <..edit files..>
 152 $ git add History.md package.json
 153 $ git commit -m '<version-number>'
 154 ```
 155
 156 ### Step 4. Identify and tag the release commit with the new release version
 157
 158 Create a lightweight tag (rather than an annotated tag) named after the new
 159 release version (eg: `4.13.3`).
 160
 161 ```sh
 162 $ git tag <version-number>
 163 ```
 164
 165 ### Step 5. Push the release branch changes and tag to github
 166
 167 The branch and tag should be pushed directly to the main repository
 168 (https://github.com/expressjs/express).
 169
 170 ```sh
 171 $ git push origin <release-branch>
 172 $ git push origin <version-number>
 173 ```
 174
 175 ### Step 6. Publish to npmjs.com
 176
 177 Ensure your local working copy is completely clean (no extra or changed files).
 178 You can use `git status` for this purpose.
 179
 180 ```sh
 181 $ npm login <npm-username>
 182 $ npm publish
 183 ```
 184
 185 **NOTE:** The version number to publish will be picked up automatically from
 186           package.json.