From 126193d8c4d68d8884754cfe74a4c085bfc1551f Mon Sep 17 00:00:00 2001
From: Roman Yurchak <rth.yurchak@gmail.com>
Date: Wed, 28 Apr 2021 19:28:11 +0200
Subject: [PATCH] DOC Add instructions for making a release (#1533)

---
 docs/development/contributing.md | 15 ++++++
 docs/development/core.md         |  1 +
 docs/development/maintainers.md  | 86 ++++++++++++++++++++++++++++++++
 docs/index.rst                   |  1 -
 4 files changed, 102 insertions(+), 1 deletion(-)
 create mode 100644 docs/development/maintainers.md

diff --git a/docs/development/contributing.md b/docs/development/contributing.md
index 64380d582..af1a53923 100644
--- a/docs/development/contributing.md
+++ b/docs/development/contributing.md
@@ -99,6 +99,10 @@ All code submissions should pass `make lint`.  Python is checked with the
 default settings of `flake8`.  C and Javascript are checked against the Mozilla
 style in `clang-format`.
 
+### Contributing to the “core” C Code
+
+See {ref}`contributing-core`.
+
 ## Documentation
 
 Documentation is a critical part of any open source project and we are very
@@ -137,6 +141,9 @@ If patches fail to apply automatically, one solution can be to
    ```
    git format-patch -<N> -N --no-stat HEAD -o <out_dir>
    ```
+## Maintainer information
+
+For information about making releases see {ref}`maintainer-information`.
 
 ## License
 
@@ -153,3 +160,11 @@ clarification on what is and isn't permitted.
 - __Gitter:__ [#pyodide](https://gitter.im/pyodide/community) channel at gitter.im
 
 [tl;drLegal entry]:https://tldrlegal.com/license/mozilla-public-license-2.0-(mpl-2)
+
+```{eval-rst}
+.. toctree::
+   :hidden:
+
+   core.md
+   maintainers.md
+```
diff --git a/docs/development/core.md b/docs/development/core.md
index ccd7bac5b..91e92a237 100644
--- a/docs/development/core.md
+++ b/docs/development/core.md
@@ -1,3 +1,4 @@
+(contributing-core)=
 # Contributing to the "core" C Code
 
 This file is intended as guidelines to help contributors trying to modify the C source files in `src/core`.
diff --git a/docs/development/maintainers.md b/docs/development/maintainers.md
new file mode 100644
index 000000000..534553b09
--- /dev/null
+++ b/docs/development/maintainers.md
@@ -0,0 +1,86 @@
+(maintainer-information)=
+# Maintainer information
+
+## Making a release
+
+For branch organization we use a variation of the [Github
+Flow](https://guides.github.com/introduction/flow/) with
+the latest release branch named `stable` (due to ReadTheDocs constraints).
+
+(making-major-release)=
+### Making a major release
+
+1. Make a new PR and for all occurrences of
+   `https://cdn.jsdelivr.net/pyodide/dev/full/` in `./docs/` replace `dev` with
+   the release version `vX.Y.Z` (note the presence of the leading `v`). This
+   also applies to `docs/conf.py`
+2. Set version in `src/pyodide-py/pyodide/__init__.py`
+3. Make sure the change log is up to date.
+    - Indicate the release date in the change log.
+    - Generate the list of contributors for the release at the end of the
+      changelog entry with,
+      ```bash
+      git shortlog -s LAST_TAG.. | cut -f2- | sort --ignore-case | tr '\n' ';' | sed 's/;/, /g;s/, $//' | fold -s
+      ```
+      where `LAST_TAG` is the tag for the last release.
+   Merge the PR.
+4. Assuming the upstream `stable` branch exists, rename it to a release branch
+   for the previous major version. For instance if last release was, `0.20.0`,
+   the corresponding release branch would be `0.20.X`,
+   ```bash
+   git fetch upstream
+   git checkout stable
+   git checkout -b 0.20.X
+   git push upstream 0.20.X
+   git branch -D stable    # delete locally
+   ```
+5. Create a tag `X.Y.Z` (without leading `v`) and push
+   it to upstream,
+   ```bash
+   git tag X.Y.Z
+   git push upstream X.Y.Z
+   ```
+   Create a new `stable` branch from this tag,
+   ```bash
+   git checkout -b stable
+   git push upstream stable --force
+   ```
+   Wait for the CI to pass and create the release on GitHub.
+6. Build the pre-built Docker image locally and push,
+   ```bash
+   docker build -t pyodide/pyodide:X.Y.Z -f Dockerfile-prebuilt --build-arg VERSION=BB .
+   docker push
+   ```
+   where `BB` is the last version of the `pyodide-env` Docker image.
+7. Revert Step 1. and increment the version in
+   `src/pyodide-py/pyodide/__init__.py` to the next version specified by
+   Semantic Versioning.
+
+### Making a minor release
+
+For a minor release, commits need to be added to the `stable` branch, ideally via a PR.
+This can be done with either,
+ - git cherry picking individual commits,
+   ```bash
+   git checkout stable
+   git pull
+   git checkout -b backport-branch
+   git cherry-puck <commit-hash>
+   ```
+ - or with interactive rebase,
+   ```bash
+   git fetch upstream
+   git checkout stable
+   git pull
+   git checkout -b backport-branch
+   git rebase -i upstream/main
+   ```
+   and indicate which commits to take from `main` in the UI.
+
+
+Then follow steps 2, 3, and 6 from {ref}`making-major-release`.
+
+### Fixing documentation for a released version
+
+Cherry pick the corresponding documentation commits to the `stable` branch. Use
+`[skip ci]` in the commit message.
diff --git a/docs/index.rst b/docs/index.rst
index f15b71eaa..861767b7d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -42,7 +42,6 @@ and understanding type conversions between Python and JavaScript.
    development/building-from-sources.md
    development/new-packages.md
    development/contributing.md
-   development/core.md
    development/testing.md
    development/debugging.md