215 lines
6.4 KiB
ReStructuredText
215 lines
6.4 KiB
ReStructuredText
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.
|