Skip to content

Commit 7e0cbff

Browse files
author
Beatriz Rizental
authored
Bug 1693260 - Add documentation about making a new release (#74)
1 parent 4ac2014 commit 7e0cbff

File tree

3 files changed

+200
-2
lines changed

3 files changed

+200
-2
lines changed

.circleci/config.yml

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,6 @@ jobs:
8080
name: Publish to npm
8181
command: export PATH=.:$PATH && (cd glean && npm publish)
8282

83-
8483
workflows:
8584
version: 2
8685
ci:
@@ -94,7 +93,7 @@ workflows:
9493
- unit-tests
9594
filters:
9695
branches:
97-
ignore: /.*/
96+
only: release
9897
tags:
9998
only: /v[0-9]+(\.[0-9]+)*/
10099
# Comment this job away until Bug 1681899 is resolved.

bin/prepare-release.sh

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
#!/usr/bin/env bash
2+
#
3+
# This Source Code Form is subject to the terms of the Mozilla Public
4+
# License, v. 2.0. If a copy of the MPL was not distributed with this
5+
# file, You can obtain one at http://mozilla.org/MPL/2.0/.
6+
7+
# Prepare a new release by updating the version numbers in all related files,
8+
# updating the changelog to include the released version.
9+
#
10+
# Optionally, it can create the release commit and tag it.
11+
#
12+
# Usage: prepare-release.sh <new version>
13+
#
14+
# Environment:
15+
#
16+
# DRY_RUN - Do not modify files or run destructive commands when set.
17+
# VERB - Log commands that are run when set.
18+
19+
set -eo pipefail
20+
21+
run() {
22+
[ "${VERB:-0}" != 0 ] && echo "+ $*"
23+
if [ "$DOIT" = y ]; then
24+
"$@"
25+
else
26+
true
27+
fi
28+
}
29+
30+
# All sed commands below work with either
31+
# GNU sed (standard on Linux distrubtions) or BSD sed (standard on macOS)
32+
SED="sed"
33+
34+
WORKSPACE_ROOT="$( cd "$(dirname "$0")/.." ; pwd -P )"
35+
36+
if [ -z "$1" ]; then
37+
echo "Usage: $(basename "$0") <new version>"
38+
echo
39+
echo "Prepare for a new release by setting the version number"
40+
exit 1
41+
fi
42+
43+
NEW_VERSION="$1"
44+
DATE=$(date +%Y-%m-%d)
45+
46+
if ! echo "$NEW_VERSION" | grep --quiet --extended-regexp '^[0-9]+\.[0-9]+\.[0-9]+(-[a-z0-9.-]+)?$'; then
47+
echo "error: Specified version '${NEW_VERSION}' doesn't match the Semantic Versioning pattern."
48+
echo "error: Use MAJOR.MINOR.PATCH versioning."
49+
echo "error: See https://semver.org/"
50+
exit 1
51+
fi
52+
53+
echo "Preparing update to v${NEW_VERSION} (${DATE})"
54+
echo "Workspace root: ${WORKSPACE_ROOT}"
55+
echo
56+
57+
GIT_STATUS_OUTPUT=$(git status --untracked-files=no --porcelain)
58+
if [ -z "$ALLOW_DIRTY" ] && [ -n "${GIT_STATUS_OUTPUT}" ]; then
59+
lines=$(echo "$GIT_STATUS_OUTPUT" | wc -l | tr -d '[:space:]')
60+
echo "error: ${lines} files in the working directory contain changes that were not yet committed into git:"
61+
echo
62+
echo "${GIT_STATUS_OUTPUT}"
63+
echo
64+
echo 'To proceed despite this and include the uncommited changes, set the `ALLOW_DIRTY` environment variable.'
65+
exit 1
66+
67+
fi
68+
69+
DOIT=y
70+
if [[ -n "$DRY_RUN" ]]; then
71+
echo "Dry-run. Not modifying files."
72+
DOIT=n
73+
fi
74+
75+
# Update Glean.js version
76+
77+
FILE=glean/package.json
78+
run $SED -i.bak -E \
79+
-e "s/^version: \"[0-9a-z.-]+\"/version: \"${NEW_VERSION}\"/" \
80+
"${WORKSPACE_ROOT}/${FILE}"
81+
run rm "${WORKSPACE_ROOT}/${FILE}.bak"
82+
83+
### Update package-lock.json
84+
85+
(cd glean && npm i --package-lock-only)
86+
87+
### CHANGELOG ###
88+
89+
FILE=CHANGELOG.md
90+
run $SED -i.bak -E \
91+
-e "s/# Unreleased changes/# v${NEW_VERSION} (${DATE})/" \
92+
-e "s/\.\.\.main/...v${NEW_VERSION}/" \
93+
"${WORKSPACE_ROOT}/${FILE}"
94+
run rm "${WORKSPACE_ROOT}/${FILE}.bak"
95+
96+
if [ "$DOIT" = y ]; then
97+
CHANGELOG=$(cat "${WORKSPACE_ROOT}/${FILE}")
98+
cat > "${WORKSPACE_ROOT}/${FILE}" <<EOL
99+
# Unreleased changes
100+
101+
[Full changelog](https://github.com/mozilla/glean.js/compare/v${NEW_VERSION}...main)
102+
${CHANGELOG}
103+
EOL
104+
fi
105+
106+
echo "Everything prepared for v${NEW_VERSION}"
107+
echo
108+
echo "Changed files:"
109+
git status --untracked-files=no --porcelain || true
110+
echo
111+
echo "Create release commit v${NEW_VERSION} now? [y/N]"
112+
read -r RESP
113+
echo
114+
if [ "$RESP" != "y" ] && [ "$RESP" != "Y" ]; then
115+
echo "No new commit. No new tag. Proceed manually."
116+
exit 0
117+
fi
118+
119+
run git add --update "${WORKSPACE_ROOT}"
120+
run git commit --message "Bumped version to ${NEW_VERSION}"
121+
122+
if git remote | grep -q upstream; then
123+
remote=upstream
124+
else
125+
remote=origin
126+
fi
127+
branch=$(git rev-parse --abbrev-ref HEAD)
128+
129+
echo "Don't forget to push this commit:"
130+
echo
131+
echo " git push $remote $branch"
132+
echo
133+
echo "Once pushed, wait for the CI build to finish: https://circleci.com/gh/mozilla/glean.js/tree/$branch"

docs/release.md

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Glean.js release process
2+
3+
Glean.js is released in the [`@mozilla/glean`](https://www.npmjs.com/package/@mozilla/glean) npm package.
4+
5+
That package will contain subpackages with Glean.js builds for each environment supported.
6+
7+
The development & release process roughly follows the [GitFlow model](https://nvie.com/posts/a-successful-git-branching-model/).
8+
9+
> **Note**: The rest of this section assumes that `upstream` points to the `https://github.com/mozilla/glean.js` repository, while `origin` points to the developer fork. For some developer workflows, `upstream` can be the same as `origin`.
10+
11+
## Standard release
12+
13+
Releases can only be done by one of the Glean maintainers.
14+
15+
- Main development branch: `main`
16+
- Main release branch: `release`
17+
- Specific release branch: `release-vX.Y.Z`
18+
19+
### Create a release branch
20+
21+
1. Create a release branch from the `main` branch:
22+
```
23+
git checkout -b release-v25.0.0 main
24+
```
25+
2. Update the changelog .
26+
1. Add any missing important changes under the `Unreleased changes` headline.
27+
2. Commit any changes to the changelog file due to the previous step.
28+
3. Run `bin/prepare-release.sh <new version>` to bump the version number.
29+
1. The new version should be the next patch, minor or major version of what is currently released.
30+
2. Let it create a commit for you.
31+
4. Push the new release branch:
32+
```
33+
git push upstream release-v25.0.0
34+
```
35+
5. Wait for CI to finish on that branch and ensure it's green:
36+
* <https://circleci.com/gh/mozilla/glean.js/tree/release-v25.0.0>
37+
6. Apply additional commits for bug fixes to this branch.
38+
* Adding large new features here is strictly prohibited. They need to go to the `main` branch and wait for the next release.
39+
40+
### Finish a release branch
41+
42+
When CI has finished and is green for your specific release branch, you are ready to cut a release.
43+
44+
1. Check out the main release branch:
45+
```
46+
git checkout release
47+
```
48+
2. Merge the specific release branch:
49+
```
50+
git merge --no-ff release-v25.0.0
51+
```
52+
3. Push the main release branch:
53+
```
54+
git push upstream release
55+
```
56+
4. Tag the release on GitHub:
57+
1. [Draft a New Release](https://github.com/mozilla/glean.js/releases/new) in the GitHub UI (`Releases > Draft a New Release`).
58+
2. Enter `v<myversion>` as the tag. It's important this is the same as the version you specified to the `prepare_release.sh` script, with the `v` prefix added.
59+
3. Select the `release` branch as the target.
60+
4. Under the description, paste the contents of the release notes from `CHANGELOG.md`.
61+
5. Wait for the CI build to complete for the tag.
62+
* You can check [on CircleCI for the running build](https://circleci.com/gh/mozilla/glean.js).
63+
6. Send a pull request to merge back the specific release branch to the development branch: <https://github.com/mozilla/glean.js/compare/main...release-v25.0.0?expand=1>
64+
* This is important so that no changes are lost.
65+
* This might have merge conflicts with the `main` branch, which you need to fix before it is merged.
66+
7. Once the above pull request lands, delete the specific release branch.

0 commit comments

Comments
 (0)