rougail/docs/release.rst

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.