python-statemachine 3.2.0__tar.gz → 3.2.2__tar.gz

python_statemachine-3.2.2/.github/workflows/pages.yml

@@ -0,0 +1,51 @@
+name: pages
+
+# Publishes the static assets served at https://fgmacedo.github.io/python-statemachine/
+# Currently: the native statechart JSON Schema, at the canonical URL used as its `$id`
+# (statemachine/io/schemas/statechart.schema.json -> /schemas/statechart/v1.json).
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - statemachine/io/schemas/statechart.schema.json
+      - .github/workflows/pages.yml
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment; don't cancel an in-progress publish.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v7
+      - name: Assemble site
+        run: |
+          mkdir -p _site/schemas/statechart
+          cp statemachine/io/schemas/statechart.schema.json _site/schemas/statechart/v1.json
+          cat > _site/index.html <<'HTML'
+          <!doctype html>
+          <meta charset="utf-8">
+          <title>python-statemachine</title>
+          <meta http-equiv="refresh" content="0; url=https://python-statemachine.readthedocs.io/">
+          <p>See the <a href="schemas/statechart/v1.json">statechart JSON Schema</a> or the
+          <a href="https://python-statemachine.readthedocs.io/">documentation</a>.</p>
+          HTML
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: _site
+      - id: deployment
+        uses: actions/deploy-pages@v5

{python_statemachine-3.2.0 → python_statemachine-3.2.2}/.github/workflows/python-package.yml

@@ -5,9 +5,9 @@ name: Python checks
 
 on:
   push:
-    branches: [ "develop" ]
+    branches: [ "main", "release/**" ]
   pull_request:
-    branches: [ "develop" ]
+    branches: [ "main" ]
 
 permissions:
   contents: read
@@ -18,19 +18,18 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14", "3.15"]
 
     steps:
-    - uses: actions/checkout@v5
-    - run: git fetch origin develop
+    - uses: actions/checkout@v7
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v6
+      uses: actions/setup-python@v7
       with:
         python-version: ${{ matrix.python-version }}
     - name: Setup Graphviz
       uses: ts-graphviz/setup-graphviz@v2
     - name: Install uv
-      uses: astral-sh/setup-uv@v8.1.0
+      uses: astral-sh/setup-uv@v10.2.0
       with:
         enable-cache: true
         cache-suffix: "python${{ matrix.python-version }}"
@@ -40,7 +39,7 @@ jobs:
       #              run ruff
       #----------------------------------------------
     - name: Linter with ruff
-      if: matrix.python-version == 3.14
+      if: matrix.python-version == 3.15
       run: |
         uv run ruff check .
         uv run ruff format --check .
@@ -55,8 +54,8 @@ jobs:
       #          upload coverage
       #----------------------------------------------
     - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v6
-      if: matrix.python-version == 3.14
+      uses: codecov/codecov-action@v7
+      if: matrix.python-version == 3.15
       with:
         token: ${{ secrets.CODECOV_TOKEN }} # not required for public repos
         directory: .

{python_statemachine-3.2.0 → python_statemachine-3.2.2}/.github/workflows/release.yml

@@ -11,20 +11,18 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: actions/checkout@v5
-
-      - run: git fetch origin develop
+      - uses: actions/checkout@v7
 
       - name: Setup Python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v7
         with:
-          python-version: '3.14'
+          python-version: '3.15'
 
       - name: Setup Graphviz
         uses: ts-graphviz/setup-graphviz@v2
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.1.0
+        uses: astral-sh/setup-uv@v10.2.0
         with:
           enable-cache: true
 
@@ -40,7 +38,7 @@ jobs:
           uv build
 
       - name: Upload  dists
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: release-dists
           path: dist/
@@ -59,7 +57,7 @@ jobs:
 
     steps:
       - name: Retrieve release distributions
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: release-dists
           path: dist/

{python_statemachine-3.2.0 → python_statemachine-3.2.2}/.pre-commit-config.yaml

@@ -9,7 +9,7 @@ repos:
         exclude: docs/auto_examples
 - repo: https://github.com/astral-sh/ruff-pre-commit
   # Ruff version.
-  rev: v0.15.17
+  rev: v0.16.10
   hooks:
     # Run the linter.
     - id: ruff

{python_statemachine-3.2.0 → python_statemachine-3.2.2}/AGENTS.md

@@ -39,7 +39,14 @@ The engine follows the SCXML run-to-completion (RTC) model with two processing l
 ### Event queues
 
 - `send()` → **external queue** (processed after current macrostep ends).
-- `raise_()` → **internal queue** (processed within the current macrostep, before external events).
+- `raise_()`, `send(internal=True)`, `Event(internal=True)` → **internal queue** (processed
+  within the current macrostep, before external events), but only when raised while the
+  machine runs a step in the same thread or task (`_running_engine` in `engines/base.py`, a
+  `ContextVar` so it is right for threads and coroutines alike). From outside a step there
+  is no macrostep to join: the trigger goes to the external queue, so its caller gets the
+  result, the exception or `TransitionNotAllowed`.
+- `delay` and `internal` together raise `InvalidDefinition`: a step takes no time.
+- Each external event is followed by its macrostep before the next external event is taken.
 
 ### Error handling (`catch_errors_as_events`)
 
@@ -296,12 +303,16 @@ enforced, so when you add or change native vocabulary:
 
 ## Git workflow
 
-- Main branch: `develop`
-- PRs target `develop`
-- Releases are tagged as `v*.*.*`
+- Trunk based development: `main` is the only long-lived branch, PRs target `main`
+- Releases are tags `vX.Y.Z` on `main`; the `latest` tag moves to every release
+- Hotfixes: `release/X.Y.x` branch cut from the tag, fixes cherry-picked from `main`
 - Signed commits preferred (`git commit -s`)
 - Use [Conventional Commits](https://www.conventionalcommits.org/) messages
   (e.g., `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`, `perf:`)
+- **NEVER bypass pre-commit hooks** (`--no-verify`, `-n`, or disabling hooks). The hooks
+  inspect every commit to keep regressions out; only the maintainer may decide to skip them.
+  If a hook modifies files (e.g. `generate-images` regenerating a diagram PNG), stage the
+  generated changes and commit again until the hooks pass — do not skip them.
 
 ## Security
 

{python_statemachine-3.2.0 → python_statemachine-3.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: python-statemachine
-Version: 3.2.0
+Version: 3.2.2
 Summary: Python Finite State Machines made easy.
 Project-URL: homepage, https://github.com/fgmacedo/python-statemachine
 Author-email: Fernando Macedo <fgmacedo@gmail.com>
@@ -18,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Home Automation
 Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.10
@@ -37,15 +38,15 @@ Description-Content-Type: text/markdown
 [![pypi](https://img.shields.io/pypi/v/python-statemachine.svg)](https://pypi.python.org/pypi/python-statemachine)
 [![downloads total](https://static.pepy.tech/badge/python-statemachine)](https://pepy.tech/project/python-statemachine)
 [![downloads](https://img.shields.io/pypi/dm/python-statemachine.svg)](https://pypi.python.org/pypi/python-statemachine)
-[![Coverage report](https://codecov.io/gh/fgmacedo/python-statemachine/branch/develop/graph/badge.svg)](https://codecov.io/gh/fgmacedo/python-statemachine)
+[![Coverage report](https://codecov.io/gh/fgmacedo/python-statemachine/branch/main/graph/badge.svg)](https://codecov.io/gh/fgmacedo/python-statemachine)
 [![Documentation Status](https://readthedocs.org/projects/python-statemachine/badge/?version=latest)](https://python-statemachine.readthedocs.io/en/latest/?badge=latest)
-[![GitHub commits since last release (main)](https://img.shields.io/github/commits-since/fgmacedo/python-statemachine/main/develop)](https://github.com/fgmacedo/python-statemachine/compare/main...develop)
+[![GitHub commits since last release](https://img.shields.io/github/commits-since/fgmacedo/python-statemachine/latest?sort=semver)](https://github.com/fgmacedo/python-statemachine/compare/latest...main)
 
 Expressive [statecharts](https://statecharts.dev/) and [FSMs](https://en.wikipedia.org/wiki/Finite-state_machine) for modern Python.
 
 <div align="center">
 
-![](https://github.com/fgmacedo/python-statemachine/blob/develop/docs/images/python-statemachine.png?raw=true)
+![](https://github.com/fgmacedo/python-statemachine/blob/main/docs/images/python-statemachine.png?raw=true)
 
 </div>
 
@@ -128,7 +129,7 @@ Generate a diagram or get a text representation with f-strings:
 sm._graph().write_png("traffic_light.png")
 ```
 
-![](https://raw.githubusercontent.com/fgmacedo/python-statemachine/develop/docs/images/readme_trafficlightmachine.png)
+![](https://raw.githubusercontent.com/fgmacedo/python-statemachine/main/docs/images/readme_trafficlightmachine.png)
 
 Parameters are injected into callbacks automatically — the library inspects the
 signature and provides only the arguments each callback needs:

{python_statemachine-3.2.0 → python_statemachine-3.2.2}/README.md

@@ -3,15 +3,15 @@
 [![pypi](https://img.shields.io/pypi/v/python-statemachine.svg)](https://pypi.python.org/pypi/python-statemachine)
 [![downloads total](https://static.pepy.tech/badge/python-statemachine)](https://pepy.tech/project/python-statemachine)
 [![downloads](https://img.shields.io/pypi/dm/python-statemachine.svg)](https://pypi.python.org/pypi/python-statemachine)
-[![Coverage report](https://codecov.io/gh/fgmacedo/python-statemachine/branch/develop/graph/badge.svg)](https://codecov.io/gh/fgmacedo/python-statemachine)
+[![Coverage report](https://codecov.io/gh/fgmacedo/python-statemachine/branch/main/graph/badge.svg)](https://codecov.io/gh/fgmacedo/python-statemachine)
 [![Documentation Status](https://readthedocs.org/projects/python-statemachine/badge/?version=latest)](https://python-statemachine.readthedocs.io/en/latest/?badge=latest)
-[![GitHub commits since last release (main)](https://img.shields.io/github/commits-since/fgmacedo/python-statemachine/main/develop)](https://github.com/fgmacedo/python-statemachine/compare/main...develop)
+[![GitHub commits since last release](https://img.shields.io/github/commits-since/fgmacedo/python-statemachine/latest?sort=semver)](https://github.com/fgmacedo/python-statemachine/compare/latest...main)
 
 Expressive [statecharts](https://statecharts.dev/) and [FSMs](https://en.wikipedia.org/wiki/Finite-state_machine) for modern Python.
 
 <div align="center">
 
-![](https://github.com/fgmacedo/python-statemachine/blob/develop/docs/images/python-statemachine.png?raw=true)
+![](https://github.com/fgmacedo/python-statemachine/blob/main/docs/images/python-statemachine.png?raw=true)
 
 </div>
 
@@ -94,7 +94,7 @@ Generate a diagram or get a text representation with f-strings:
 sm._graph().write_png("traffic_light.png")
 ```
 
-![](https://raw.githubusercontent.com/fgmacedo/python-statemachine/develop/docs/images/readme_trafficlightmachine.png)
+![](https://raw.githubusercontent.com/fgmacedo/python-statemachine/main/docs/images/readme_trafficlightmachine.png)
 
 Parameters are injected into callbacks automatically — the library inspects the
 signature and provides only the arguments each callback needs:

{python_statemachine-3.2.0 → python_statemachine-3.2.2}/docs/actions.md

@@ -145,10 +145,13 @@ levels of the hierarchy.
 
 ```{note}
 The generic `on_exit_state()` and `on_enter_state()` callbacks also fire
-once per state in the set, but the `state` parameter is bound to the
-transition's `source` or `target` — not the individual state being
-exited/entered. Use `event_data` if you need the full context, or prefer
-state-specific callbacks for clarity.
+once per state in the set, and the `state` parameter is bound to the
+individual state being exited or entered, so you can tell each level of a
+compound apart. On entry, `target` matches `state`; on exit, `source`
+matches `state`. The opposite endpoint stays fixed at the transition's
+`source` (on entry) or `target` (on exit). Prefer state-specific callbacks
+(`on_exit_<state>`, `on_enter_<state>`) when you want to target one level
+directly.
 ```
 
 ```{seealso}

{python_statemachine-3.2.0 → python_statemachine-3.2.2}/docs/async.md

@@ -152,19 +152,32 @@ processing loop at a time. The sync engine does not support this pattern.
 Under the hood, the async engine attaches an `asyncio.Future` to each
 externally enqueued event. The coroutine that acquires the processing lock
 resolves each event's future as it processes the queue. Callers that didn't
-acquire the lock simply `await` their future.
+acquire the lock `await` their future, or the release of the lock, to take
+the loop over if the coroutine holding it was cancelled.
 
 ```{note}
-Futures are only created for **external** events sent from outside the
-processing loop. Events triggered from within callbacks (via `send()` or
-`raise_()`) follow the {ref}`run-to-completion <rtc-model>` model — they
-are enqueued and processed within the current macrostep.
+Futures are created for every event sent from outside the processing loop,
+including one declared `internal=True`, which goes to the external queue
+when there is no macrostep to join. Events triggered from within callbacks
+(via `send()` or `raise_()`) follow the {ref}`run-to-completion <rtc-model>`
+model: they are enqueued and processed by the running loop.
 ```
 
 If an exception occurs during processing (with `catch_errors_as_events=False`),
-the exception is routed to the caller whose event caused it. Other callers
+the exception is routed to the caller whose event raised it. Other callers
 whose events were still pending will also receive the exception, since the
-processing loop clears the queue on failure.
+processing loop clears the queue on failure. A caller is answered once the
+macrostep of its event ends, so an exception raised by the internal events or
+eventless transitions that follow its event reaches it too. When no coroutine
+awaits that event, because a callback sent it or its caller was cancelled while
+awaiting it, the exception goes to the coroutine running the processing loop.
+
+If the coroutine running the processing loop is cancelled, only that coroutine
+stops: a coroutine awaiting a queued event takes the loop over, and returns
+once the queue is empty. With no coroutine waiting, the events left in the
+queue run at the next `send()`. The caller of the event being processed when
+the cancellation hit gets a `StateMachineError`, since its callbacks were
+interrupted.
 
 
 (syncengine)=

{python_statemachine-3.2.0 → python_statemachine-3.2.2}/docs/behaviour.md

@@ -28,7 +28,7 @@ SCXML-compliant behavior provides more predictable semantics.
 ```{warning}
 This page describes runtime *semantics*. If you **load SCXML documents** via
 `SCXMLProcessor`, note that SCXML is executable content: by default the
-datamodel is evaluated with a restricted AST whitelist and `<script>` is
+datamodel is evaluated with a restricted AST allowlist and `<script>` is
 rejected, so untrusted documents cannot execute arbitrary code. Pass
 `trusted=True` only for SCXML you control. See the 3.2.0 release notes and
 GHSA-v4jc-pm6r-3vj8.
@@ -158,6 +158,10 @@ When `True` (SCXML default), runtime exceptions in action callbacks
 internal `error.execution` events. When `False` (legacy default), exceptions
 propagate normally to the caller.
 
+This flag only governs exceptions raised **inside** an action callback. An event
+that doesn't match any enabled transition is a different case, controlled by
+{ref}`allow_event_without_transition <behaviour>` instead.
+
 ```{note}
 {ref}`Validators <validators>` are **not** affected by this flag — they
 always propagate exceptions to the caller, regardless of the

{python_statemachine-3.2.0 → python_statemachine-3.2.2}/docs/conf.py

@@ -174,7 +174,7 @@ html_theme_options = {
     "navigation_with_keys": True,
     "top_of_page_buttons": ["view", "edit"],
     "source_repository": "https://github.com/fgmacedo/python-statemachine/",
-    # "source_branch": "develop",
+    # "source_branch": "main",
     "source_directory": "docs/",
 }
 
@@ -271,7 +271,7 @@ html_context = {
     "display_github": True,  # Integrate GitHub
     "github_user": "fgmacedo",  # Username
     "github_repo": "python-statemachine",  # Repo name
-    "github_version": "develop",  # Version
+    "github_version": "main",  # Version
     "conf_py_path": "/docs/",  # Path in the checkout to the docs root
 }
 

{python_statemachine-3.2.0 → python_statemachine-3.2.2}/docs/contributing.md

@@ -104,9 +104,11 @@ Ready to contribute? Here's how to set up `python-statemachine` for local develo
 
         pre-commit install
 
-3. Create a branch for local development:
+3. Create a branch for local development, starting from an up-to-date `main`:
 
-        git checkout -b <name-of-your-bugfix-or-feature>
+        git switch main
+        git pull --ff-only origin main
+        git switch -c <name-of-your-bugfix-or-feature>
 
 4. Make changes to the code.
 
@@ -144,8 +146,9 @@ Ready to contribute? Here's how to set up `python-statemachine` for local develo
         git commit -s -m "Your detailed description of your changes."
         git push origin name-of-your-bugfix-or-feature
 
-1. Create a pull request on the original repository for your changes to be reviewed and potentially
-merged. Be sure to follow the project's code of conduct and contributing guidelines.
+1. Create a pull request on the original repository, targeting the `main` branch, for your
+changes to be reviewed and potentially merged. Be sure to follow the project's code of conduct
+and contributing guidelines.
 
 1. Use `exit` to leave the virtual environment.
 
@@ -162,44 +165,40 @@ Before you submit a pull request, check that it meets these guidelines:
 
 ## Releasing a New Version
 
-This project uses [git-flow](https://github.com/nvie/gitflow) for release management and
-publishes to PyPI automatically via GitHub Actions when a version tag is pushed.
+This project follows [trunk based development](https://trunkbaseddevelopment.com/): `main` is
+the only long-lived branch and every release is a tag on it. Pushing a `vX.Y.Z` tag triggers
+the GitHub Actions workflow that publishes to PyPI.
 
 ### Prerequisites
 
-- You must be on the `develop` branch with a clean working tree.
-- `git-flow` must be installed and initialized:
+- You must be on the `main` branch with a clean working tree, up to date with `origin/main`:
 
   ```shell
-  brew install git-flow   # macOS
-  git flow init           # use main for production, develop for next release
+  git switch main
+  git pull --ff-only origin main
   ```
 
-- All changes intended for the release must already be merged into `develop`.
+- All changes intended for the release must already be merged into `main`.
 
 ### Step-by-step release process
 
 The following steps use version `X.Y.Z` as a placeholder. Replace it with the actual version
 number (e.g., `2.6.0`).
 
-#### 1. Start the release branch
-
-```shell
-git checkout develop
-git pull origin develop
-git flow release start X.Y.Z
-```
-
-This creates and switches to a `release/X.Y.Z` branch based on `develop`.
-
-#### 2. Bump the version number
+#### 1. Bump the version number
 
 Update the version string in **both** files:
 
 - `pyproject.toml` — the `version` field under `[project]`
 - `statemachine/__init__.py` — the `__version__` variable
 
-#### 3. Update translations
+Then refresh the lock file, which records the project's own version:
+
+```shell
+uv lock
+```
+
+#### 2. Update translations
 
 Extract new translatable strings, merge them into all existing `.po` files, translate the
 new entries, and compile:
@@ -211,6 +210,10 @@ uv run pybabel update -i statemachine/locale/statemachine.pot -d statemachine/lo
 uv run pybabel compile -d statemachine/locale/ -D statemachine
 ```
 
+The `en` catalog keeps empty `msgstr` entries: English falls back to the source strings.
+When a translation needs the placeholders in a different order, number them (`'{0}'`,
+`'{2}'`, `'{1}'`) instead of reordering bare `{}`, which would swap the values.
+
 ```{note}
 The `.pot` and `.mo` files are git-ignored. Only the `.po` source files are committed.
 The compiled `.mo` files may cause test failures if your system locale matches a translated
@@ -218,9 +221,10 @@ language (error messages will appear translated instead of in English). Delete t
 verifying translations work: `rm -f statemachine/locale/*/LC_MESSAGES/statemachine.mo`
 ```
 
-#### 4. Write release notes
+#### 3. Write release notes
 
-Create `docs/releases/X.Y.Z.md` documenting all changes since the previous release. Include
+Create `docs/releases/X.Y.Z.md` documenting all changes since the previous release, if
+the pull requests did not already start it. Include
 sections for new features, bugfixes, performance improvements, and miscellaneous changes.
 Reference GitHub issues/PRs where applicable.
 
@@ -230,7 +234,10 @@ major version section).
 Update any related documentation pages (e.g., if a bugfix adds a new behavior that users
 should know about).
 
-#### 5. Run linters and tests
+Replace the `*Not released yet*` line under the title with the release date (e.g.
+`*October 13, 2026*`).
+
+#### 4. Run linters and tests
 
 ```shell
 uv run ruff check .
@@ -241,43 +248,36 @@ uv run pytest -n auto
 
 All checks must pass before committing.
 
-#### 6. Commit
+#### 5. Commit
 
 Stage all changed files and commit. The pre-commit hooks will run ruff, mypy, and pytest
-automatically.
+automatically. If a hook rewrites a file (e.g. `fix end of files` on the `.po` files), stage
+it and commit again.
 
 ```shell
 git add <files>
-git commit -m "chore: prepare release X.Y.Z"
+git commit -s -m "chore: prepare release X.Y.Z"
 ```
 
-#### 7. Finish the release
+#### 6. Tag the release
 
-```shell
-git flow release finish X.Y.Z -m "vX.Y.Z"
-```
-
-This will:
-- Merge `release/X.Y.Z` into `main`
-- Create an annotated tag `X.Y.Z` on `main`
-- Merge `main` back into `develop`
-- Delete the `release/X.Y.Z` branch
+Create an annotated `vX.Y.Z` tag and move the `latest` tag to the same commit:
 
-```{note}
-If tagging fails (e.g., GPG or editor issues), create the tag manually and re-run:
-`git tag -a X.Y.Z -m "vX.Y.Z"` then `git flow release finish X.Y.Z -m "vX.Y.Z"`.
+```shell
+git tag -a vX.Y.Z -m "vX.Y.Z"
+git tag -f latest
 ```
 
-#### 8. Update the `latest` tag and push
+#### 7. Push
 
 ```shell
-git tag latest -f
-git push origin main develop --tags -f
+git push origin main vX.Y.Z
+git push -f origin latest
 ```
 
-Force-pushing tags is needed to move the `latest` tag.
+Force-pushing is needed only to move the `latest` tag.
 
-#### 9. Verify the release
+#### 8. Verify the release
 
 The tag push triggers the `release` GitHub Actions workflow (`.github/workflows/release.yml`),
 which will:
@@ -290,7 +290,7 @@ which will:
 Monitor the workflow run at `https://github.com/fgmacedo/python-statemachine/actions` to
 confirm the release was published successfully.
 
-#### 10. Publish the GitHub release
+#### 9. Publish the GitHub release
 
 Create the GitHub release from the freshly pushed tag using the release notes file as the
 body. Two adjustments are needed when going from MyST/Sphinx markdown to GitHub-flavored
@@ -312,9 +312,43 @@ Then create the release. Use the converted notes as the body:
 gh release create vX.Y.Z \
   --title "vX.Y.Z" \
   --notes-file /tmp/release-X.Y.Z-notes.md \
-  --target main \
   --verify-tag
 ```
 
 Confirm the rendered release at
 `https://github.com/fgmacedo/python-statemachine/releases/tag/vX.Y.Z`.
+
+### Hotfix releases
+
+Use a hotfix release when `main` already has unreleased changes that must not ship yet, but a
+fix needs to reach users of the last release. If `main` is releasable as is, just cut a
+regular release from it.
+
+1. Land the fix on `main` first, through a regular pull request with tests.
+
+1. Create the release branch from the released tag (or reuse it if it already exists):
+
+        git switch -c release/X.Y.x vX.Y.Z
+
+1. Cherry-pick the fix commits from `main`, keeping a reference to their origin:
+
+        git cherry-pick -x <sha>
+
+1. On the release branch, bump the patch version and write the release notes, then commit
+   `chore: prepare release X.Y.Z` exactly as in the regular process.
+
+1. Tag and push. Pushing the branch runs the `Python checks` workflow before you tag; move
+   `latest` only if this is the highest version released so far:
+
+        git push -u origin release/X.Y.x
+        git tag -a vX.Y.Z -m "vX.Y.Z"
+        git push origin vX.Y.Z
+        git tag -f latest && git push -f origin latest
+
+1. Publish the GitHub release as in the regular process.
+
+1. Cherry-pick the `chore: prepare release X.Y.Z` commit back into `main` so the version and
+   release notes stay in sync. A conflict only happens if `main` was already bumped; keep
+   `main`'s version and take the release notes.
+
+The release branch can be deleted once the tag exists; the tag keeps the commits reachable.