docs: Update release process
DELETE
CONTRIBUTING.md
-
-## Making a Release
-
-* Create a branch off `master`. Unless stated otherwise, all code blocks below
- are examples from the 0.12.7 release of the "ses" package. Further steps below
- assume you are in the directory of the package being released, so let's `cd`
- there first.
- ```
- $ cd packages/ses
- $ git checkout -b release-12-7
- ```
-* Ensure `NEWS.md` captures all user-visible changes in prose that are
- user-relevant.
- Ideally, the news file would conform to the [Keep a
- Changelog](https://keepachangelog.com) specification, but ours do not at this
- time, so adhere to the prevailing pattern.
-* Choose a new release number based on the principles of [Semantic
- Versioning](https://semver.org) and whether the news includes breaking
- changes (major number), added features (minor number), or just big fixes
- (patch number).
- Do not use 0.0.x versions, only x.y.z or 0.x.y.
- Versions 0.0.x can't be patched without changes to the dependee.
- Major version bumps should be avoided to the extent that is possible if there
- are any third-party users. A new package name is often better than a major
- version bump.
- ```
- 0.12.7
- ```
-* Update the title of the first entry in `NEWS.md` to include the new version
- number and the timestamp.
- ```
- ## Release 0.12.7 (5-April-2021)
- ```
-* Update `package.json` version.
- ```json
- {
- "name": "ses",
- "version": "0.12.7",
- ...
- }
- ```
-* Update every other `package.json` in this repository that takes a dependency
- on the changed package.
- ```json
- "dependencies": {
- ...
- "ses": "^0.12.7",
- ...
- }
- ```
-* Create a version commit titled "chore($PACKAGENAME): v$VERSION"
- ```
- $ git commit -a -m 'chore(ses): v0.12.7'
- ```
-* Use `npm pack` and `tar tf "$PACKAGENAME-v$VERSION.tgz"` to spot-check
- whether the generated archive contains only and all relevant files.
- We now have a lint rule that ensures that `files` in `package.json` includes
- at least `src`, `dist`, and all `LICENSE*` files, and we can remove this step
- as our confidence grows in our release mechanisms.
- ```
- $ npm pack
- ```
-* `npm publish` to publish the version.
- Being a member of the project or organization and having two-factor
- authentication may be necessary. It may be necessary to login with
- `npm login`. You can check with `npm whoami`.
- ```
- $ npm whoami
- # if it does not show you logged in, then do
- $ npm login
- # two factor authentication stuff
- $ npm publish
- ```
-* Go to the npm web page for the package, for example
- [https://www.npmjs.com/package/ses](https://www.npmjs.com/package/ses).
- ***However*** do not be alarmed if it does not show your new version for
- a distressingly long time. Instead you can verify the version with
- ```
- $ npm view ses
- ```
-* Only after a successful round of validation and publication, create
- a tag `$PACKAGENAME-v$VERSION` with `git tag -a "$TAG" -m "$TAG"`.
- ```
- $ git tag -a "ses-v0.12.7" -m "ses-v0.12.7"
- ```
-* Update version in `package.json` by suffixing `+1-dev` to the release
- version.
- ```json
- {
- "name": "ses",
- "version": "0.12.7+1-dev",
- ...
- }
- ```
-* Add a `Next release` `* No changes yet` section to the head of `NEWS.md`.
- ```
- User-visible changes in SES:
-
- ## Next Release
-
- No changes yet.
-
- ## Release 0.12.7 (5-April-2021)
- ```
-* Stage the changes made above.
- ```
- $ git add package.json NEWS.md
- ```
-* Commit with the message `chore($PACKAGENAME): Back to development with
- v$VERSION+1-dev`.
- ```
- $ git commit -m 'chore(ses): Back to development with v0.12.7+1-dev'
- ```
-* Create a pull request from this branch.
- ```
- $ git push --set-upstream origin release-12-7
- ```
-
- Create a merge commit. Notice the little triangle on the merge button and select
- "Create a merge commit" from the drop down menu.
- Do not rebase.
- Do not squash.
- Rebasing or squashing will remove the tag from the history of the `master`
- branch.
-
-* Selecting "Create a merge commit" in that drop down is sticky. Assuming you
- normally want "Squash and merge", be sure to set it back to that at your
- next opportunity.

ADD
MAINTAINERS.md
+# Making a Release
+
+* Create a release branch.
+
+ ```sh
+ now=`date -u +%Y-%m-%d-%H-%M-%S`
+ git checkout -b release-$now
+ ```
+
+* Create the release CHANGELOGs.
+
+ ```sh
+ yarn lerna version --no-push --conventional-graduate --no-git-tag-version
+ ```
+
+ Use `--conventional-prerelease` instead of `--conventional-graduate` if you
+ just want to generate a dev release.
+
+* Commit the results.
+
+ ```sh
+ git commit -am 'chore: lerna version'
+ ```
+
+* Identify `NEWS.md` files that need to be updated.
+ Ensure `NEWS.md` captures all user-visible changes in prose that are
+ user-relevant.
+
+ ```sh
+ git grep '# Next'
+ ```
+
+ For each of these files, copy the version number and timestamp from the
+ adjacent `CHANGELOG.md` generated in the previous step.
+ For example,
+
+ ```diff
+ -# Next release
+ +# 0.5.1 (2021-08-12)
+ ```
+
+* Commit the results.
+
+ ```sh
+ git commit -am 'chore: Update release notes'
+ ```
+
+* Push the branch.
+
+ ```sh
+ git push -u origin release-$now
+ ```
+
+* Create a pull request and request a review.
+ This is an opportunity to:
+
+ - verify that the changes pass tests under continuous integration,
+ - reflect on whether the automatically chosen version numbers tell an
+ accurate story about the backward and mutual compatibility of the packages
+ you are about to publish,
+ - and to verify that all user-facing changes are noted in the NEWS.md files
+ with appropriate migration advice when necessary.
+
+* When your reviewer has approved your release, use `git rebase -i
+ origin/master` to remove the automatically generated `chore: lerna version`
+ commit.
+
+* Recreate the changelogs with the current date *and* generate tags for the new
+ versions. This is the effect of removing the `--no-git-tag-version` flag.
+
+ ```sh
+ yarn lerna version --no-push --conventional-graduate
+ ```
+
+* Commit the results.
+
+ ```sh
+ git commit -am 'chore: lerna version'
+ ```
+
+* Force push these changes back to the pull request branch.
+
+ ```sh
+ git push origin -f release-$now
+ ```
+
+* Ensure your dependency solution is fresh and rebuild all generated assets.
+
+ ```sh
+ yarn install
+ yarn build
+ ```
+
+* Publish the versions to npm.
+ Being a member of the project or organization and having two-factor
+ authentication may be necessary. It may be necessary to login with
+ `npm login`. You can check with `npm whoami`.
+
+ ```
+ $ npm whoami
+ # if it does not show you logged in, then do
+ $ npm login
+ # two factor authentication stuff
+ $ yarn lerna publish from-package
+ # repeat this command until all packages are successfully published
+ ```
+
+* To verify that packages were published, go to the npm web page for the
+ package, for example
+ [https://www.npmjs.com/package/ses](https://www.npmjs.com/package/ses).
+ ***However*** do not be alarmed if it does not show your new version for
+ a distressingly long time. Instead you can verify the version with
+
+ ```
+ $ npm view ses
+ ```
+
+* Merge the release PR into master.
+ DO NOT REBASE OR SQUASH OR YOU WILL LOSE REFERENCES TO YOUR TAGS.
+
+ Notice the little triangle on the merge button and select "Create a merge
+ commit" from the drop down menu.
+ Do not rebase.
+ Do not squash.
+ Rebasing or squashing will remove the tag from the history of the `master`
+ branch.
+
+* Selecting "Create a merge commit" in that drop down is sticky. Assuming you
+ normally want "Squash and merge", be sure to set it back to that at your
+ next opportunity.
+
+* Push the released tags to Github.
+
+ ```sh
+ git tag -l | egrep -e '@[0-9]+\.[0-9]+\.[0-9]+$' | xargs git push origin
+ ```
+
+## More information
+
+To get help for the command-line options that will affect these commands, use:
+
+```sh
+yarn lerna version --help
+yarn lerna publish --help
+```

docs: Update release process