From 6f7ced583c298b461d5cab9e25a6409ff4dfdae7 Mon Sep 17 00:00:00 2001
From: Prashant Mital <5883388+prashantmital@users.noreply.github.com>
Date: Thu, 24 Sep 2020 16:12:17 -0700
Subject: [PATCH] Document Motor release process (#92)

---
 RELEASE.rst | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 release.sh  | 30 +++++++++++++++++++++++
 2 files changed, 98 insertions(+)
 create mode 100644 RELEASE.rst
 create mode 100755 release.sh

diff --git a/RELEASE.rst b/RELEASE.rst
new file mode 100644
index 00000000..24c70930
--- /dev/null
+++ b/RELEASE.rst
@@ -0,0 +1,68 @@
+==============
+Motor Releases
+==============
+
+Versioning
+----------
+
+Motor's version numbers follow `semantic versioning <http://semver.org/>`_:
+each version number is structured "major.minor.patch". Patch releases fix
+bugs, minor releases add features (and may fix bugs), and major releases
+include API changes that break backwards compatibility (and may add features
+and fix bugs).
+
+In between releases we add .devN to the version number to denote the version
+under development. So if we just released 2.3.0, then the current dev
+version might be 2.3.1.dev0 or 2.4.0.dev0. When we make the next release we
+replace all instances of 2.x.x.devN in the docs with the new version number.
+
+https://www.python.org/dev/peps/pep-0440/
+
+Release Process
+---------------
+
+Motor ships a `pure Python wheel <https://packaging.python.org/guides/distributing-packages-using-setuptools/#pure-python-wheels>`_
+and a `source distribution <https://packaging.python.org/guides/distributing-packages-using-setuptools/#source-distributions>`_.
+
+#. Motor is tested on Evergreen. Ensure that the latest commit is passing CI as
+   expected: https://evergreen.mongodb.com/waterfall/motor.
+
+#. Check JIRA to ensure all the tickets in this version have been completed.
+
+#. Add release notes to `doc/changelog.rst`. Generally just summarize/clarify
+   the git log, but you might add some more long form notes for big changes.
+
+#. Search and replace the `devN` version number w/ the new version number (see
+   note above in `Versioning`_). Make sure version number is updated in
+   `setup.py` and `motor/__init__.py`. Commit the change and tag the release.
+   Immediately bump the version number to `dev0` in a new commit::
+
+     $ # Bump to release version number
+     $ git commit -a -m "BUMP <release version number>"
+     $ git tag -a "<release version number>" -m "BUMP <release version number>"
+     $ # Bump to dev version number
+     $ git commit -a -m "BUMP <dev version number>"
+     $ git push
+     $ git push --tags
+
+#. Build the release packages by running the `release.sh`
+   script on macOS::
+
+     $ git clone git@github.com:mongodb/motor.git
+     $ cd motor
+     $ git checkout "<release version number>"
+     $ ./release.sh
+
+   This will create the following distributions::
+
+     $ ls dist
+     motor-<version>.tar.gz
+     motor-<version>-py3-none-any.whl
+
+#. Upload all the release packages to PyPI with twine::
+
+     $ python3 -m twine upload dist/*
+
+#. Trigger a build of the docs on https://readthedocs.org/.
+
+#. Announce!
diff --git a/release.sh b/release.sh
new file mode 100755
index 00000000..5d4e56da
--- /dev/null
+++ b/release.sh
@@ -0,0 +1,30 @@
+#!/bin/bash -ex
+
+# This script should be run on macOS.
+# It will create the following distributions:
+# motor-<version>.tar.gz
+# motor-<version>-py3-none-any.whl
+
+set -o xtrace   # Write all commands first to stderr
+set -o errexit  # Exit the script with error if any of the commands fail
+
+# Only build distributions with Python 3.5.2 or later.
+python3 -c "import sys; exit(sys.version_info < (3, 5, 2))"
+if [ $? -ne 0 ]; then
+  echo "ERROR: Run this script with Python 3.5.2 or later."
+  exit 1
+fi
+
+# Cleanup destinations
+rm -rf build
+rm -rf dist
+
+# Build the source dist first
+python3 setup.py sdist
+
+# Build the wheel
+python3 setup.py bdist_wheel
+
+# Cleanup
+rm -rf build
+ls dist