From fd9061317eccfc1ac8d4eb258fc2e57964e1470e Mon Sep 17 00:00:00 2001
From: Pierre Sassoulas <pierre.sassoulas@gmail.com>
Date: Sun, 28 Feb 2021 19:44:28 +0100
Subject: [PATCH] Upgrade the doc about release

---
 doc/release.md  | 74 +++++++++++++++++++++++++++++++++++++++++++++++++
 doc/release.txt | 30 --------------------
 2 files changed, 74 insertions(+), 30 deletions(-)
 create mode 100644 doc/release.md
 delete mode 100644 doc/release.txt

diff --git a/doc/release.md b/doc/release.md
new file mode 100644
index 0000000000..66df2e99b3
--- /dev/null
+++ b/doc/release.md
@@ -0,0 +1,74 @@
+# Releasing an astroid version
+
+So, you want to release the ``X.Y.Z`` version of astroid ?
+
+## Process
+
+1. Preparation
+   1. Check if the dependencies of the package are correct
+   2. Update ``numversion`` in ``__pkginfo__``, ``dev_version`` should also be None when you tag.
+   3. Put the version numbers, and the release date into the changelog
+   4. Put the release date into the ``What's new`` section.
+   5. Generate the new copyright notices for this release:
+
+```bash
+pip3 install copyrite
+copyrite --contribution-threshold 1 --change-threshold 3 --backend-type \
+git --aliases=.copyrite_aliases . --jobs=8
+# During the commit pre-commit and pyupgrade will remove the encode utf8
+# automatically
+```
+
+   6. Submit your changes in a merge request.
+
+2. Make sure the tests are passing on Travis/GithubActions:
+   https://travis-ci.org/PyCQA/astroid/
+
+3. Do the actual release by tagging the master with ``astroid-X.Y.Z`` (ie  ``astroid-1.6.12``
+   for example). Travis should deal with the release process once the tag is pushed
+   with `git push origin --tags`
+
+## Manual Release
+
+Following the previous steps, for a manual release run the following commands:
+
+```bash
+git clean -fdx && find . -name '*.pyc' -delete
+python setup.py sdist --formats=gztar bdist_wheel
+twine upload dist/*
+# don't forget to tag it as well
+```
+
+## Post release
+
+### New branch to create for major releases
+
+The master branch will have all the new features for the ``X.Y+1`` version
+
+If you're doing a major release, you need to create the ``X.Y`` branch
+where we will cherry-pick bugs to release the ``X.Y.Z+1`` minor versions
+
+### Milestone handling
+
+We move issue that were not done in the next milestone and block release only
+if it's an issue labelled as blocker.
+
+### Files to update after releases
+
+#### Changelog
+
+* Create a new section, with the name of the release ``X.Y.Z+1`` on the ``X.Y`` branch.
+* If it's a major release, also create a new section for ``X.Y+1.0`` on the master branch
+
+You need to add the estimated date when it is going to be published. If
+no date can be known at that time, we should use ``Undefined``.
+
+#### Whatsnew
+
+If it's a major release, create a new ``What's new in astroid X.Y+1`` document
+Take a look at the examples from ``doc/whatsnew``.
+
+### Versions
+
+Update ``numversion`` to ``X.Y+1.0`` in ``__pkginfo__`` for ``master`` and to ``X.Y.Z+1`` for the ``X.Y`` branch.
+``dev_version`` should also be back to an integer after the tag.
diff --git a/doc/release.txt b/doc/release.txt
deleted file mode 100644
index b330c7c900..0000000000
--- a/doc/release.txt
+++ /dev/null
@@ -1,30 +0,0 @@
-Release Process
-===============
-
-1. Preparation
-   1. Check if the dependencies of the package are correct
-   2. Update the version number in __pkginfo__
-   3. Put the version number and the release date into the changelog
-   4. Submit your changes.
-
-2. If releasing a major or minor version, generate the new copyright notices for this release:
-
- $ copyrite --contribution-threshold 1 --change-threshold 3 --backend-type git --aliases=.copyrite_aliases . --jobs=8
-
-3. Make sure the tests are passing on Travis:
-   https://travis-ci.org/PyCQA/astroid/
-
-4. Add a new tag 'astroid-$VERSION'
-
-5. Publish all remaining changes to the Github repository:
-   https://github.com/PyCQA/astroid
-
-6. Run
-
-   $ git clean -fd && find . -name '*.pyc' -delete
-   $ rm dist/*
-   $ python setup.py sdist --formats=gztar bdist_wheel
-   $ twine upload dist/*
-
-
-   to release a new version to PyPI.