From 6750e4f429386c6c147a658ab48baecc605d77e0 Mon Sep 17 00:00:00 2001
From: zorun <github@bitsofnetworks.org>
Date: Sat, 30 Oct 2021 21:23:27 +0200
Subject: [PATCH] Update release documentation (#893)

Co-authored-by: Baptiste Jonglez <git@bitsofnetworks.org>
---
 docs/contributing.rst | 53 +++++++++++++++++++++++++++++++++++++++++--
 docs/upgrade.rst      |  2 ++
 2 files changed, 53 insertions(+), 2 deletions(-)

diff --git a/docs/contributing.rst b/docs/contributing.rst
index f9b9f9cc..6f78c4ff 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -220,6 +220,45 @@ And to produce a HTML doc in the `docs/_output` folder::
 How to release?
 ===============
 
+Requirements
+------------
+
+To create a new release, make sure you fullfil all requirements:
+
+- Are you a maintainer of the pypi package?
+- Are you sure you have no local tags?  They will all be published
+  to the github process as part of the release process
+- Make sure you have a ``~/.pypirc`` file with the following content,
+  replacing ``YOUR_PYPI_USERNAME`` with your real username::
+
+    [distutils]
+    index-servers =
+        pypi
+    
+    [pypi]
+    username:YOUR_PYPI_USERNAME
+
+Choosing a version number
+-------------------------
+
+The project follows `semantic versioning <https://semver.org/>`_.
+To sum things up:
+
+- **if there is a breaking change since the last release:** increase the major
+  version number (11.X.Y -> 12.0.0). Example of breaking changes: drop support
+  for an old version of python, new setting without default value (requires
+  an admin to configure the new setting), changed URL paths, any other incompatible
+  change. Make sure to :ref:`document the upgrade process<upgrade>`.
+
+- **if there is a significant new feature or a new setting:** increase the minor
+  version number (11.4.Y -> 11.5.0). Make sure to :ref:`document any new settings<configuration>`.
+
+- **if it's mostly bugfixes and small changes:** increase the patch version number
+  (11.4.8 -> 11.4.9)
+
+Making the release
+------------------
+
 In order to issue a new release, follow the following steps:
 
 - Merge remaining pull requests;
@@ -235,12 +274,22 @@ In order to issue a new release, follow the following steps:
     make update-translations
     make build-translations
 
-Once this is done, let's release!::
+- If you're not completely sure of yourself at this point, you
+  can optionally: create a new branch, push it, open a pull request,
+  check the CI result, and then merge the branch to master.
+
+Once this is done, make sure your local git repository is on the master branch,
+and let's release!::
 
     make release
 
-This will publish the new version to `the Python Package Index <https://pypi.org>`_ (PyPI).
+This will publish the new version to `the Python Package Index <https://pypi.org>`_ (PyPI)
+and publish a tag in the git repository.
 
 .. note:: The above command will prompt for version number, handle
           :file:`CHANGELOG.rst` and :file:`setup.cfg` updates, package creation,
           pypi upload. It will prompt you before each step to get your consent.
+
+Finally, create a release on Github and copy the relevant changelog extract into it.
+Unfortunately, you need to manually convert links to Markdown...
+We have a `discussion to automate this step <https://github.com/spiral-project/ihatemoney/issues/894>`_.
diff --git a/docs/upgrade.rst b/docs/upgrade.rst
index 53185413..1ccfdbed 100644
--- a/docs/upgrade.rst
+++ b/docs/upgrade.rst
@@ -1,3 +1,5 @@
+.. _upgrade:
+
 Upgrading
 #########