docs(release): release procedure with commitizen
add commitizen conf in the pyproject.toml
This commit is contained in:
gwen
parent
7afb2c860c
commit
af57c8349c
3 changed files with 221 additions and 2 deletions
|
|
@ -84,6 +84,7 @@ Rougail
|
||||||
:titlesonly:
|
:titlesonly:
|
||||||
:caption: Developper notes
|
:caption: Developper notes
|
||||||
|
|
||||||
|
release
|
||||||
developer
|
developer
|
||||||
documentation
|
documentation
|
||||||
|
|
||||||
|
|
@ -92,7 +93,7 @@ Rougail
|
||||||
|
|
||||||
install
|
install
|
||||||
naming_convention
|
naming_convention
|
||||||
|
|
||||||
.. rubric:: Index page
|
.. rubric:: Index page
|
||||||
|
|
||||||
- :ref:`genindex`
|
- :ref:`genindex`
|
||||||
|
|
|
||||||
215
docs/release.rst
Normal file
215
docs/release.rst
Normal file
|
|
@ -0,0 +1,215 @@
|
||||||
|
Release procedure
|
||||||
|
=================
|
||||||
|
|
||||||
|
We are using Comitizen.
|
||||||
|
|
||||||
|
We are automating vi semantic versionning (SemVer) + CHANGELOG with Commitizen
|
||||||
|
|
||||||
|
Goal
|
||||||
|
----
|
||||||
|
|
||||||
|
With each release, a single command (``cz bump --changelog``) will
|
||||||
|
automatically:
|
||||||
|
|
||||||
|
- Analyze your commits (Conventional Commits)
|
||||||
|
- Calculate the new version (patch, minor, major)
|
||||||
|
- Update the version in your files
|
||||||
|
- Generate/update the CHANGELOG.md - Create the release commit and Git tag
|
||||||
|
|
||||||
|
Installation
|
||||||
|
------------
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
# Global installation or within your virtual environment
|
||||||
|
pip install commitizen
|
||||||
|
|
||||||
|
# Verify installation
|
||||||
|
cz version
|
||||||
|
|
||||||
|
Working with Conventional Commits
|
||||||
|
---------------------------------
|
||||||
|
|
||||||
|
Creating standardized commits
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Two methods:
|
||||||
|
|
||||||
|
**Method 1: Interactive guide (recommended for beginners)**
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
cz commit
|
||||||
|
|
||||||
|
An assistant guides you step by step: 1. Choose the change type
|
||||||
|
(``fix``, ``feat``, ``docs``, etc.) 2. Enter the message 3. Describe the
|
||||||
|
scope (optional) 4. Indicate breaking changes (if any)
|
||||||
|
|
||||||
|
**Method 2: Manually**
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
# Bug fix → patch (0.1.0 → 0.1.1)
|
||||||
|
git commit -m "fix: fix connection timeout"
|
||||||
|
|
||||||
|
# New feature → minor (0.1.0 → 0.2.0)
|
||||||
|
git commit -m "feat: add OAuth2 authentication"
|
||||||
|
|
||||||
|
# Breaking change → major (0.1.0 → 1.0.0)
|
||||||
|
git commit -m "feat: new REST API
|
||||||
|
|
||||||
|
BREAKING CHANGE: removed v1 endpoints"
|
||||||
|
|
||||||
|
Commit types and version impact
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
+-----------------------+-----------------------+-----------------------+
|
||||||
|
| Commit type | Incrementation | Example |
|
||||||
|
+=======================+=======================+=======================+
|
||||||
|
| ``fix:`` | **patch** (+0.0.1) | ``f |
|
||||||
|
| | | ix: fix display bug`` |
|
||||||
|
+-----------------------+-----------------------+-----------------------+
|
||||||
|
| ``perf:`` | **patch** (+0.0.1) | ``per |
|
||||||
|
| | | f: optimize queries`` |
|
||||||
|
+-----------------------+-----------------------+-----------------------+
|
||||||
|
| ``feat:`` | **minor** (+0.1.0) | ``f |
|
||||||
|
| | | eat: add PDF export`` |
|
||||||
|
+-----------------------+-----------------------+-----------------------+
|
||||||
|
| ``BREAKING CHANGE:`` | **major** (+1.0.0) | any type + |
|
||||||
|
| (in message) | | ``BREAKING CHANGE:`` |
|
||||||
|
+-----------------------+-----------------------+-----------------------+
|
||||||
|
|
||||||
|
--------------
|
||||||
|
|
||||||
|
The magic command - Creating a release
|
||||||
|
--------------------------------------
|
||||||
|
|
||||||
|
When you’re ready to publish a new version:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
# Analyzes commits since last tag and executes the release
|
||||||
|
cz bump --changelog
|
||||||
|
|
||||||
|
What this command does exactly:
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
1. **Analyzes** all commits since the last Git tag
|
||||||
|
2. **Calculates** the next version (patch/minor/major)
|
||||||
|
3. **Updates** the version in all listed files
|
||||||
|
4. **Generates/updates** the ``CHANGELOG.md`` (adds the new entry at the
|
||||||
|
top)
|
||||||
|
5. **Automatically commits** the changes with the message:
|
||||||
|
``"bump: version X.Y.Z"``
|
||||||
|
6. **Creates a Git tag** (format ``vX.Y.Z``)
|
||||||
|
|
||||||
|
Concrete execution example:
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
$ cz bump --changelog
|
||||||
|
INFO: Starting version bump from 1.0.0 to 1.1.0
|
||||||
|
INFO: Updating version in pyproject.toml
|
||||||
|
INFO: Updating version in src/my_project/__init__.py
|
||||||
|
INFO: Generating CHANGELOG.md
|
||||||
|
INFO: Created commit: bump: version 1.1.0
|
||||||
|
INFO: Created tag: v1.1.0
|
||||||
|
|
||||||
|
--------------
|
||||||
|
|
||||||
|
Managing the auto-generated CHANGELOG
|
||||||
|
-------------------------------------
|
||||||
|
|
||||||
|
The ``CHANGELOG.md`` file will look like this:
|
||||||
|
|
||||||
|
.. code:: markdown
|
||||||
|
|
||||||
|
## v1.1.0 (2024-01-15)
|
||||||
|
|
||||||
|
### Feat
|
||||||
|
|
||||||
|
- add OAuth2 authentication
|
||||||
|
- add PDF export
|
||||||
|
|
||||||
|
### Fix
|
||||||
|
|
||||||
|
- fix connection timeout
|
||||||
|
|
||||||
|
## v1.0.0 (2024-01-10)
|
||||||
|
|
||||||
|
### Breaking Changes
|
||||||
|
|
||||||
|
- removed v1 endpoints
|
||||||
|
|
||||||
|
### Feat
|
||||||
|
|
||||||
|
- first version of REST API
|
||||||
|
|
||||||
|
**You can customize the template** by adding to ``pyproject.toml``:
|
||||||
|
|
||||||
|
.. code:: toml
|
||||||
|
|
||||||
|
[tool.commitizen]
|
||||||
|
# ... existing configuration ...
|
||||||
|
changelog_template = "custom_changelog_template.j2" # Custom Jinja2 template
|
||||||
|
|
||||||
|
--------------
|
||||||
|
|
||||||
|
Pushing the release to Git
|
||||||
|
--------------------------
|
||||||
|
|
||||||
|
After ``cz bump --changelog``, you have a commit and a tag locally. Push
|
||||||
|
them:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
# Push the commit and tags
|
||||||
|
git push --follow-tags
|
||||||
|
|
||||||
|
--------------
|
||||||
|
|
||||||
|
Useful daily commands
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
+-----------------------------------+-----------------------------------+
|
||||||
|
| Command | Purpose |
|
||||||
|
+===================================+===================================+
|
||||||
|
| ``cz commit`` | Interactive guide to create a |
|
||||||
|
| | conventional commit |
|
||||||
|
+-----------------------------------+-----------------------------------+
|
||||||
|
| ``cz bump --changelog`` | **The main command**: bumps |
|
||||||
|
| | version + CHANGELOG |
|
||||||
|
+-----------------------------------+-----------------------------------+
|
||||||
|
| ``cz check`` | Checks if your last commit |
|
||||||
|
| | follows the convention |
|
||||||
|
+-----------------------------------+-----------------------------------+
|
||||||
|
| ``cz version`` | Displays current version |
|
||||||
|
| | (according to Commitizen) |
|
||||||
|
+-----------------------------------+-----------------------------------+
|
||||||
|
| ``cz changelog`` | Generates only the CHANGELOG |
|
||||||
|
| | without bumping |
|
||||||
|
+-----------------------------------+-----------------------------------+
|
||||||
|
| ``cz bump --prerelease alpha`` | Creates a pre-release version |
|
||||||
|
| | (e.g., 1.0.0-alpha.1) |
|
||||||
|
+-----------------------------------+-----------------------------------+
|
||||||
|
|
||||||
|
--------------
|
||||||
|
|
||||||
|
Summary: The ideal workflow in 3 steps
|
||||||
|
--------------------------------------
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
# 1. During development: standardized commits
|
||||||
|
git add .
|
||||||
|
cz commit # or git commit -m "feat: ..."
|
||||||
|
|
||||||
|
# 2. When you're ready for a release
|
||||||
|
cz bump --changelog
|
||||||
|
|
||||||
|
# 3. Push to Git
|
||||||
|
git push --follow-tags
|
||||||
|
|
||||||
|
**And that’s it!** Version bumped, CHANGELOG generated, tag created, all
|
||||||
|
automated.
|
||||||
|
|
@ -38,7 +38,10 @@ dev = [
|
||||||
|
|
||||||
[tool.commitizen]
|
[tool.commitizen]
|
||||||
name = "cz_conventional_commits"
|
name = "cz_conventional_commits"
|
||||||
tag_format = "$version"
|
tag_format = "v$version"
|
||||||
|
version_files = ["pyproject.toml:version"]
|
||||||
version_scheme = "semver"
|
version_scheme = "semver"
|
||||||
version_provider = "pep621"
|
version_provider = "pep621"
|
||||||
update_changelog_on_bump = true
|
update_changelog_on_bump = true
|
||||||
|
changelog_file = "CHANGELOG.md"
|
||||||
|
changelog_incremental = true
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue