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:
|
||||
:caption: Developper notes
|
||||
|
||||
release
|
||||
developer
|
||||
documentation
|
||||
|
||||
|
|
@ -92,7 +93,7 @@ Rougail
|
|||
|
||||
install
|
||||
naming_convention
|
||||
|
||||
|
||||
.. rubric:: Index page
|
||||
|
||||
- :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]
|
||||
name = "cz_conventional_commits"
|
||||
tag_format = "$version"
|
||||
tag_format = "v$version"
|
||||
version_files = ["pyproject.toml:version"]
|
||||
version_scheme = "semver"
|
||||
version_provider = "pep621"
|
||||
update_changelog_on_bump = true
|
||||
changelog_file = "CHANGELOG.md"
|
||||
changelog_incremental = true
|
||||
|
|
|
|||
Loading…
Reference in a new issue