docs(release): update release documentation

LavaMoat · Aug 1, 2023 · 71cafd5 · 71cafd5
1 parent 6bba5af
commit 71cafd5
Showing 1 changed file with 67 additions and 41 deletions.
diff --git a/RELEASE.md b/RELEASE.md
@@ -3,34 +3,51 @@
 LavaMoat follows [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
 This lays out part of the steps involved in drafting and publishing any of the LavaMoat packages monotonically.
 
-## 0. Prerequirements
-
-- One package per release
-- Releases are always monotonically from current `main`.
-- Ensure your local `main` branch is up to date
-- Perform any necessary manual or local tests not covered in automatic tests
-- Review the commits since the last release: `$ git log main...$(git log --grep "${PKGDIR}/version - ${CURRENT_VERSION}" --format=tformat:%h) packages/${PKGDIR}`
-- Review the diff since the last release: `$ git diff main $(git log --grep "${PKGDIR}/version - ${CURRENT_VERSION}" --format=tformat:%h) packages/${PKGDIR}`
-- Determine the new version number based on the nature of changes
-  - Follow up with author or reviewers if the SemVer-nature of an included change is unclear before proceeding
-
-## 1. Preparing your release
-
-1) Bumping version
-  - Create a new branch: `git checkout -b release-${PKGDIR}-${VERSION}`
-  - Bump the `version` field in `packages/{PKGDIR}/package.json` in an individual commit
-    - Commit title must be of format `${PKGDIR}/version - ${VERSION}`
-    - Commit body must contain an exhaustive list of changes to the package since last release (commit hashes and/or merged PR numbers).
-  - Build, lint, and test the package
-2) Bumping dependents
-  - Identify any other packages in the monorepo that depend on the current version of this package and should have their versions bumped
-    - Useful: `$ find packages -maxdepth 2 -name package.json -exec jq '[.name, .dependencies["PKGNAME"], .devDependencies["PKGNAME"]] | select(.[1] or .[2])|@tsv' {} -r \;`
-  - Perform updates of dependents if necessary in additional commit
-  - Build, lint, and test any updated dependants
-    - Keep in mind that as long as the version range of the dependency is satisfied by the locally checked out package, internal dependencies will be linked to that. Otherwise, it's fetched from the configured registry like any other dependency.
-3) Review
-  - Build, lint, and test the workspace
-  - `git diff release-${PKGDIR}-${VERSION} main` should only contain version and dependency bumps in `package.json` files, and the corresponding changes in `yarn.lock`
+## Automated Release Process
+
+The [Release Please][] GitHub Action automates all parts of the release process _except_ the publish to the public npm registry.
+
+This is how it works:
+
+1. A contributor creates a PR targeting the default branch (`main`) with commit messages in the [Conventional Commits][] format. PRs may contain changes across packages. _Note: a PR will fail checks if the commit is not in a valid format._
+2. Once this PR is merged into its target branch (`main`), Release Please creates _one pull request per affected package_. The description in each PR will contain the changelog and the changesets will contain updates to the `package.json` and `CHANGELOG.md` files. _Expect the repo to have at least one of these open at any time._
+3. When additional contributor PRs are merged into `main`, all open Release Please PRs will be rebased and updated to reflect these changes.
+4. A maintainer reviews a Release Please PR, and when they are satisfied with the changes, they rebase into `main`. This will trigger Release Please again with the following behavior:
+   1. Tag the changeset with a package name and version number.
+   2. Create a new [GitHub Release](https://github.com/LavaMoat/LavaMoat/releases) for this tag containing the changelog.
+   3. As before, create or update any extant Release Please PRs reflecting the new release commit in `main` (if needed).
+
+Once a Release Please PR has been merged into `main`, _the maintainer who merged **should** publish the package to npm_. See the next section.
+
+## Humans Publish to npm
+
+[Lerna][] handles the publishing duties for us, but a human must trigger it. The process is straightforward:
+
+1. Ensure you are logged in to npm; use `npm login` and/or `npm whoami`. **Do not do this on an untrusted machine.**
+1. In your `LavaMoat` working copy, checkout `main` and pull it from `origin`.
+1. Execute `npm ci` to install using the lockfile (`package-lock.json`). This will obliterate any `node_modules` and `packages/*/node_modules` directories.
+1. Execute `npm run publish`. Lerna will publish _all_ packages that have not yet been published. This is important, because publishing one package at a time could cause a package (e.g., `lavapack`) to be published depending on an unpublished dependency (`lavamoat-core).
+
+2) Bumping version
+
+- Create a new branch: `git checkout -b release-${PKGDIR}-${VERSION}`
+- Bump the `version` field in `packages/{PKGDIR}/package.json` in an individual commit
+  - Commit title must be of format `${PKGDIR}/version - ${VERSION}`
+  - Commit body must contain an exhaustive list of changes to the package since last release (commit hashes and/or merged PR numbers).
+- Build, lint, and test the package
+
+3. Bumping dependents
+
+- Identify any other packages in the monorepo that depend on the current version of this package and should have their versions bumped
+  - Useful: `$ find packages -maxdepth 2 -name package.json -exec jq '[.name, .dependencies["PKGNAME"], .devDependencies["PKGNAME"]] | select(.[1] or .[2])|@tsv' {} -r \;`
+- Perform updates of dependents if necessary in additional commit
+- Build, lint, and test any updated dependants
+  - Keep in mind that as long as the version range of the dependency is satisfied by the locally checked out package, internal dependencies will be linked to that. Otherwise, it's fetched from the configured registry like any other dependency.
+
+4. Review
+
+- Build, lint, and test the workspace
+- `git diff release-${PKGDIR}-${VERSION} main` should only contain version and dependency bumps in `package.json` files, and the corresponding changes in `yarn.lock`
 
 ## 2. Submitting a release PR
 
@@ -47,27 +64,33 @@ Request review from the LavaMoat/devs team. Await approval.
 This part can be done by a different person.
 
 0. Prerequisites
-  - PR reviewed
-  - Credentials to a user on npmjs.org with publish permissions to the relevant package
-  - Push permissions to https://github.com/LavaMoat/LavaMoat `main` branch
-  - Ensure you are doing this from a secure environment and handle the npm credentials with utmost care
-    - In particular, keep deployment and development/testing systems separate
-  - Fresh clone to ensure a clean and consistent state
+
+- PR reviewed
+- Credentials to a user on npmjs.org with publish permissions to the relevant package
+- Push permissions to https://github.com/LavaMoat/LavaMoat `main` branch
+- Ensure you are doing this from a secure environment and handle the npm credentials with utmost care
+  - In particular, keep deployment and development/testing systems separate
+- Fresh clone to ensure a clean and consistent state
+
 1. `$ cd ${WORKSPACE_ROOT}`
 2. `$ git checkout main`
 3. `$ git pull` - just to make sure it's fresh
 4. `$ git merge --ff-only release-${PKGDIR}-${VERSION}`
 5. Install and build workspace
-  - `$ NODE_ENV=production yarn --frozen-lockfile --check-files --production=false`
-  - `$ NODE_ENV=production yarn setup`
-  - `$ NODE_ENV=production yarn build`
+
+- `$ NODE_ENV=production yarn --frozen-lockfile --check-files --production=false`
+- `$ NODE_ENV=production yarn setup`
+- `$ NODE_ENV=production yarn build`
+
 6. `$ yarn test:prep && yarn test`
 7. `$ git push origin main`
 8. `$ git tag ${PKGDIR}-v${VERSION}`
 9. `$ git push origin ${PKGDIR}-v${VERSION}`
 10. Authenticate as your user on npmjs.org:
-  - `$ npm login`
-  - `$ npm whoami` should now return your npmjs.org username
+
+- `$ npm login`
+- `$ npm whoami` should now return your npmjs.org username
+
 11. `$ cd packages/{PKGDIR}`
 12. `$ npm publish`
 13. Close down environment and ensure npm token is no longer present
@@ -76,7 +99,7 @@ This part can be done by a different person.
 
 # Release dependency
 
-*when releasing, go top-down*
+_when releasing, go top-down_
 
 ```mermaid
 flowchart BT;
@@ -97,7 +120,6 @@ flowchart BT;
 
 ```
 
-
 | folder                    | npm name                            | deps                                            |
 | ------------------------- | ----------------------------------- | ----------------------------------------------- |
 | aa                        | @lavamoat/aa                        |                                                 |
@@ -112,3 +134,7 @@ flowchart BT;
 | tofu                      | lavamoat-tofu                       |                                                 |
 | viz                       | lavamoat-viz                        | lavamoat-core                                   |
 | yarn-plugin-allow-scripts | @lavamoat/yarn-plugin-allow-scripts |                                                 |
+
+[Release Please]: https://github.com/google-github-actions/release-please-action
+[Conventional Commits]: https://www.conventionalcommits.org/en/v1.0.0/#summary
+[Lerna]: https://lerna.js.org