docs: Document how we release

Polyconseil · Oct 9, 2018 · 43415c8 · 43415c8
1 parent a7ce93f
commit 43415c8
Show file tree

Hide file tree

Showing 3 changed files with 29 additions and 0 deletions.
diff --git a/Makefile b/Makefile
@@ -14,5 +14,8 @@ quality:
 	python setup.py check --strict --metadata --restructuredtext
 	pylint --reports=no setup.py cid
 
+release: clean
+	fullrelease
+
 test:
 	py.test tests
diff --git a/docs/index.rst b/docs/index.rst
@@ -13,5 +13,6 @@ Topics
    installation
    api
    contributing
+   releasing
    authors
    history
diff --git a/docs/releasing.rst b/docs/releasing.rst
@@ -0,0 +1,25 @@
+=======================
+Releasing a new version
+=======================
+
+We use the excellent `zest.releaser`_ tool to make new releases. There
+is a Makefile rule that does a bit more cleaning beforehand. Just
+type::
+
+    make release
+
+And then follow the instructions.
+
+We try to use `semantic versioning`_, i.e. use MAJOR.MINOR.PATCH
+version numbers with:
+
+- MAJOR version when we make incompatible API changes;
+- MINOR version when we add functionality in a backwards-compatible manner;
+- PATCH version when we make backwards-compatible bug fixes.
+
+Although the distinction between MINOR and PATCH has not always been
+followed, the changelog should be clear enough.
+
+
+.. _zest.releaser: https://zestreleaser.readthedocs.io/en/latest/
+.. _semantic versioning: https://semver.org/