Add document for release (#1007)

Co-authored-by: Kunshan Wang <wks1986@gmail.com>

Author: qinsoon

docs/team/pull_request.md

@@ -42,26 +42,27 @@ This process should be done automatically by [`auto-merge.yml`](https://github.c
 when an mmtk-core PR is merged and the `binding-refs` comment is present.
 
 1. Make sure there is no other PR in this merging process. If so, resolve those first.
-1. Make sure all the PRs (the mmtk-core PR, the binding PRs, and the associated PRs in the VM repo if any) are ready to merge.
-1. For each binding PR that we need to merge:
+2. Make sure all the PRs (the mmtk-core PR, the binding PRs, and the associated PRs in the VM repo if any) are ready to merge.
+3. Make sure there is a comment that provides `binding-refs` for all the binding PRs.
+4. For each binding PR that we need to merge:
    1. If the binding PR has an assocate PR in the VM repo, merge the VM PR first. Once it is merged, we will have a commit hash (we refer to it as `{vm_commit}`).
-   1. Update `mmtk/Cargo.toml` in the binding:
+   2. Update `mmtk/Cargo.toml` in the binding:
       * Find the section `[package.metadata.{binding-name}]`.
       * Update the field `{binding-name}_repo` if necessary. It should point to our VM fork, such as `https://github.com/mmtk/{binding-name}.git`.
       * Update the field `{binding-name}_version`. It should point to the new commit hash `{vm_commit}`.
       * Commit the change.
-1. Merge the mmtk-core PR.
-1. When a new commit is pushed to `master`, `auto-merge.yml` will be triggered.
-1. The binding PRs should be updated and auto merge will be eanbled for the PR. Keep an eye until the PRs are all merged. Resolve any
+5. Merge the mmtk-core PR.
+6. When a new commit is pushed to `master`, `auto-merge.yml` will be triggered.
+7. The binding PRs should be updated and auto merge will be eanbled for the PR. Keep an eye until the PRs are all merged. Resolve any
    issue that prevents the PR from being auto merged (e.g. flaky tests).
 
 #### Manual merging process
 
 If `auto-merge.yml` failed for any reason, or if we have to manually merge binding PRs, this is the process to follow:
 
-1. Follow Step 1-4 in the auto merging process.
-1. When a new commit is pushed to `master`, we record the commit hash (as `{mmtk_core_commit}`).
-1. For each binding PR that we need to merge:
+1. Follow Step 1-5 in the auto merging process. (Step 3 is optional)
+2. When a new commit is pushed to `master`, we record the commit hash (as `{mmtk_core_commit}`).
+3. For each binding PR that we need to merge:
    1. Update `mmtk/Cargo.toml` in the binding:
       * Find the `mmtk` dependency under `[dependencies]`.
       * Update the field `git` if necessary. It should point to our mmtk-core repo, `https://github.com/mmtk/mmtk-core.git`.

docs/team/release.md

@@ -0,0 +1,87 @@
+# Release
+
+This documents how MMTk is currently released in the pre-1.0 stage.
+
+## Release Cycle
+
+We maintain a 6-week release cycle. A release is usually cut at the end of a week (Friday).
+
+## Release Scope
+
+MMTk releases include MMTk core and the officially supported bindings. They share the same version number as MMTk core.
+
+The current releases include the following bindings:
+* OpenJDK
+* JikesRVM
+
+The current releases do not include the following bindings:
+* Julia: We have made good progress on the binding development, and we will include it soon.
+* Ruby: We have made good progress on the binding development, and we will include it soon.
+* V8: We currently lack of resources to work on the binding.
+
+## Release Process
+
+### Create PRs to bump the version number
+
+Create pull requests for each repository (mmtk-core, and binding repos that will be included in the release).
+We use semantic versioning for MMTk core, and use the same version number for all the bindings in the same release.
+If the current version is `0.X.x`, the new version should be `0.X+1.0`.
+
+#### MMTk core
+
+The PR should include these changes:
+
+1. Bump version in `Cargo.toml`.
+2. Bump version in `macros/Cargo.toml`. Use the new version for the `mmtk-macros` dependency in `Cargo.toml`
+3. Update `CHANGELOG.md`:
+   1. Add a section for the new version number and the cut-off date (when the PR is created)
+   2. Add change logs for the release. The following shows one convenient way to do it. If there is a better way, we should adopt.
+      1. Auto generate the list of changes for the release on Github. Click on [`releases`](https://github.com/mmtk/mmtk-core/releases),
+         then click [`Draft a new release`](https://github.com/mmtk/mmtk-core/releases/new). Enter the new version tag,
+         and the `Generate release notes` button should be avaialble. Copy the notes as the change logs to `CHANGELOG.md`.
+         Close the release page without tagging a release.
+      2. Categorize the changes in `CHANGELOG.md`. We use these categories: Plan, Policy, Allocator, Scheduler, API, Misc.
+4. Update the pinned Rust version in `rust-toolchain` if necessary.
+   1. Talk with system admin for our CI machines, and check if there is a newer Rust version that we should be using.
+   2. If we update to a new Rust version, make necessary changes to the code base.
+
+#### Bindings
+
+The PR should include these changes:
+
+1. Bump version in `mmtk/Cargo.toml`. Use the same version as MMTk core.
+2. Update `CHANGELOG.md`, similar to the process in MMTk core.
+3. Update the pinned Rust version in `rust-toolchain` if the Rust version is updated for MMTk core.
+4. Update the dependency of `mmtk` in `mmtk/Cargo.toml` to use the MMTk core PR. Update `Cargo.lock`.
+
+#### Merging PRs
+
+We should have a mmtk-core PR and multiple binding PRs. When all the PRs are approved, we can start merging the PRs.
+The merging is the same as ['Merging a PR with API breaking changes' in pull_request.md](./pull_request.md#merging-a-pr-with-api-breaking-changes).
+
+### Tag releases
+
+Once the PRs are merged, we can tag releases on Github.
+
+1. Go to 'Create a new release' for each involved repository. E.g. https://github.com/mmtk/mmtk-core/releases/new for `mmtk-core.`
+2. Enter the new version (prefixed with `v`) in the box of 'Choose a tag'. Use the default 'target' (`master`).
+3. Enter the release title
+   * `MMTk 0.x.0`
+   * `MMTk OpenJDK Binding 0.x.0`
+4. Copy the markdown section for this version in the `CHANGELOG.md` as the description for the release.
+5. Tick 'Set as a pre-release'.
+6. Click 'Publish release'.
+
+### Post release checklist
+
+1. Keep an eye on the badges in [README](https://github.com/mmtk/mmtk-core#mmtk)
+   * crates.io: Once a release is tagged for `mmtk-core`, [cargo-publish.yml](https://github.com/mmtk/mmtk-core/blob/master/.github/workflows/cargo-publish.yml) should be trigger to publish `mmtk-core` to `crates.io`. https://crates.io/crates/mmtk should show the new version.
+   * docs: Document hosting: Once `mmtk-core` is published to `crates.io`, a job should be queue'd for document generation on `docs.rs`. https://docs.rs/mmtk/latest/mmtk/ should show
+   the docs for the new version once the generation is done.
+2. Keep an eye on the CI status for the latest commit in MMTk core.
+3. Do point release for fixing severe issues. Currently we normally do not need point releases. Normal bug fixes or any other issues can be fixed in the next release.
+   But in rare cases, such as the current tagged release cannot build, cannot run, or it somehow fails in publishing, we may need to do a point release.
+   * If there is no other commit in `master` yet, doing a point release follows exactly the same process above. Depending on the changes, we may or may not need a point release
+     for the bindings.
+   * If there are commits in `master` that we do not want to include in the point release, the point release should be in a separate branch in the upstream repository.
+     The changes for the point release should be merged back to `master`.