Bug 1693260 - Add documentation about making a new release

.circleci/config.yml

@@ -80,7 +80,6 @@ jobs:
           name: Publish to npm
           command: export PATH=.:$PATH && (cd glean && npm publish)
 
-
 workflows:
   version: 2
   ci:
@@ -94,7 +93,7 @@ workflows:
             - unit-tests
           filters:
             branches:
-              ignore: /.*/
+              only: release
             tags:
               only: /v[0-9]+(\.[0-9]+)*/
       # Comment this job away until Bug 1681899 is resolved.

bin/prepare-release.sh

@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+#
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+# Prepare a new release by updating the version numbers in all related files,
+# updating the changelog to include the released version.
+#
+# Optionally, it can create the release commit and tag it.
+#
+# Usage: prepare-release.sh <new version>
+#
+# Environment:
+#
+# DRY_RUN - Do not modify files or run destructive commands when set.
+# VERB    - Log commands that are run when set.
+
+set -eo pipefail
+
+run() {
+  [ "${VERB:-0}" != 0 ] && echo "+ $*"
+  if [ "$DOIT" = y ]; then
+      "$@"
+  else
+      true
+  fi
+}
+
+# All sed commands below work with either
+# GNU sed (standard on Linux distrubtions) or BSD sed (standard on macOS)
+SED="sed"
+
+WORKSPACE_ROOT="$( cd "$(dirname "$0")/.." ; pwd -P )"
+
+if [ -z "$1" ]; then
+    echo "Usage: $(basename "$0") <new version>"
+    echo
+    echo "Prepare for a new release by setting the version number"
+    exit 1
+fi
+
+NEW_VERSION="$1"
+DATE=$(date +%Y-%m-%d)
+
+if ! echo "$NEW_VERSION" | grep --quiet --extended-regexp '^[0-9]+\.[0-9]+\.[0-9]+(-[a-z0-9.-]+)?$'; then
+    echo "error: Specified version '${NEW_VERSION}' doesn't match the Semantic Versioning pattern."
+    echo "error: Use MAJOR.MINOR.PATCH versioning."
+    echo "error: See https://semver.org/"
+    exit 1
+fi
+
+echo "Preparing update to v${NEW_VERSION} (${DATE})"
+echo "Workspace root: ${WORKSPACE_ROOT}"
+echo
+
+GIT_STATUS_OUTPUT=$(git status --untracked-files=no --porcelain)
+if [ -z "$ALLOW_DIRTY" ] && [ -n "${GIT_STATUS_OUTPUT}" ]; then
+    lines=$(echo "$GIT_STATUS_OUTPUT" | wc -l | tr -d '[:space:]')
+    echo "error: ${lines} files in the working directory contain changes that were not yet committed into git:"
+    echo
+    echo "${GIT_STATUS_OUTPUT}"
+    echo
+    echo 'To proceed despite this and include the uncommited changes, set the `ALLOW_DIRTY` environment variable.'
+    exit 1
+
+fi
+
+DOIT=y
+if [[ -n "$DRY_RUN" ]]; then
+    echo "Dry-run. Not modifying files."
+    DOIT=n
+fi
+
+# Update Glean.js version
+
+FILE=glean/package.json
+run $SED -i.bak -E \
+    -e "s/^version: \"[0-9a-z.-]+\"/version: \"${NEW_VERSION}\"/" \
+    "${WORKSPACE_ROOT}/${FILE}"
+run rm "${WORKSPACE_ROOT}/${FILE}.bak"
+
+### Update package-lock.json
+
+(cd glean && npm i --package-lock-only)
+
+### CHANGELOG ###
+
+FILE=CHANGELOG.md
+run $SED -i.bak -E \
+    -e "s/# Unreleased changes/# v${NEW_VERSION} (${DATE})/" \
+    -e "s/\.\.\.main/...v${NEW_VERSION}/" \
+    "${WORKSPACE_ROOT}/${FILE}"
+run rm "${WORKSPACE_ROOT}/${FILE}.bak"
+
+if [ "$DOIT" = y ]; then
+    CHANGELOG=$(cat "${WORKSPACE_ROOT}/${FILE}")
+    cat > "${WORKSPACE_ROOT}/${FILE}" <<EOL
+# Unreleased changes
+
+[Full changelog](https://github.com/mozilla/glean.js/compare/v${NEW_VERSION}...main)
+${CHANGELOG}
+EOL
+fi
+
+echo "Everything prepared for v${NEW_VERSION}"
+echo
+echo "Changed files:"
+git status --untracked-files=no --porcelain || true
+echo
+echo "Create release commit v${NEW_VERSION} now? [y/N]"
+read -r RESP
+echo
+if [ "$RESP" != "y" ] && [ "$RESP" != "Y" ]; then
+    echo "No new commit. No new tag. Proceed manually."
+    exit 0
+fi
+
+run git add --update "${WORKSPACE_ROOT}"
+run git commit --message "Bumped version to ${NEW_VERSION}"
+
+if git remote | grep -q upstream; then
+    remote=upstream
+else
+    remote=origin
+fi
+branch=$(git rev-parse --abbrev-ref HEAD)
+
+echo "Don't forget to push this commit:"
+echo
+echo "    git push $remote $branch"
+echo
+echo "Once pushed, wait for the CI build to finish: https://circleci.com/gh/mozilla/glean.js/tree/$branch"

docs/release.md

@@ -0,0 +1,66 @@
+# Glean.js release process
+
+Glean.js is released in the [`@mozilla/glean`](https://www.npmjs.com/package/@mozilla/glean) npm package.
+
+That package will contain subpackages with Glean.js builds for each environment supported.
+
+The development & release process roughly follows the [GitFlow model](https://nvie.com/posts/a-successful-git-branching-model/).
+
+> **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`.
+
+## Standard release
+
+Releases can only be done by one of the Glean maintainers.
+
+- Main development branch: `main`
+- Main release branch: `release`
+- Specific release branch: `release-vX.Y.Z`
+
+### Create a release branch
+
+1. Create a release branch from the `main` branch:
+    ```
+    git checkout -b release-v25.0.0 main
+    ```
+2. Update the changelog .
+    1. Add any missing important changes under the `Unreleased changes` headline.
+    2. Commit any changes to the changelog file due to the previous step.
+3. Run `bin/prepare-release.sh <new version>` to bump the version number.
+    1. The new version should be the next patch, minor or major version of what is currently released.
+    2. Let it create a commit for you.
+4. Push the new release branch:
+    ```
+    git push upstream release-v25.0.0
+    ```
+5. Wait for CI to finish on that branch and ensure it's green:
+    * <https://circleci.com/gh/mozilla/glean.js/tree/release-v25.0.0>
+6. Apply additional commits for bug fixes to this branch.
+    * Adding large new features here is strictly prohibited. They need to go to the `main` branch and wait for the next release.
+
+### Finish a release branch
+
+When CI has finished and is green for your specific release branch, you are ready to cut a release.
+
+1. Check out the main release branch:
+    ```
+    git checkout release
+    ```
+2. Merge the specific release branch:
+    ```
+    git merge --no-ff release-v25.0.0
+    ```
+3. Push the main release branch:
+    ```
+    git push upstream release
+    ```
+4. Tag the release on GitHub:
+    1. [Draft a New Release](https://github.com/mozilla/glean.js/releases/new) in the GitHub UI (`Releases > Draft a New Release`).
+    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.
+    3. Select the `release` branch as the target.
+     4. Under the description, paste the contents of the release notes from `CHANGELOG.md`.
+5. Wait for the CI build to complete for the tag.
+    * You can check [on CircleCI for the running build](https://circleci.com/gh/mozilla/glean.js).
+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>
+    * This is important so that no changes are lost.
+    * This might have merge conflicts with the `main` branch, which you need to fix before it is merged.
+7. Once the above pull request lands, delete the specific release branch.