From 54a1de07362e07d84104039ecbad434f76758a38 Mon Sep 17 00:00:00 2001
From: Santiago Fraire Willemoes <santiwilly@gmail.com>
Date: Thu, 20 Aug 2026 16:54:06 +0100
Subject: [PATCH] docs: improve scm tutorial

---
 docs/tutorials/release-scm.md | 45 ++++++++++++++++++++++-------------
 1 file changed, 28 insertions(+), 17 deletions(-)

diff --git a/docs/tutorials/release-scm.md b/docs/tutorials/release-scm.md
index f8db1321bb..00ae9d70fa 100644
--- a/docs/tutorials/release-scm.md
+++ b/docs/tutorials/release-scm.md
@@ -1,5 +1,7 @@
 # Releasing with the SCM Version Provider
 
+In this tutorial, you will learn how to bump the version using the `scp` version provider; as you can't use `cz bump`.
+
 ## About
 
 When `version_provider` is set to `scm`, Commitizen reads the version directly from your Git tags instead of a config file.
@@ -11,34 +13,26 @@ tag_format = "v${version}"
 version_provider = "scm"
 ```
 
-This means `cz bump` cannot complete its usual job of writing the new version anywhere (see [Why can't I bump with SCM?](#why-cant-i-bump-with-scm) below).
+This means `cz bump` cannot complete its usual job of writing the new version anywhere (see [Why can't I bump with SCM?](#why-cant-i-bump-with-scm) below). In the next section, you will learn how to do it anyways.
 
 ## Creating a New Version Tag Manually
 
-To release a new version without an extra commit, compute the next tag yourself and create it directly:
+To release a new version without an extra commit and using tags,
+you can compute the next tag using `cz version` and then, you can manually create the tag directly.
+
+In this example, we create an annotated tag with the changelog as the tag message, using just `git`.
 
 ```sh
 next_version=$(cz version --project --next --tag)
-git tag --annotate "$next_version" --message "$next_version"
+cz changelog --incremental --dry-run --unreleased-version "$next_version" > .changelog.md
+git tag --annotate "$next_version" -F .changelog.md
 git push --follow-tags
 ```
 
 !!! tip
     Wrap this in a CI job to fully automate releases when using the `scm` provider using [setup-cz](https://github.com/commitizen-tools/setup-cz)
 
-## Why Can't I Bump with SCM?
-
-When you run `cz bump`, Commitizen normally creates a new commit that updates the version somewhere,
-either in `.cz.toml`, or in `pyproject.toml` if you're using Python, or `Cargo.toml` for rust.
-It may also update `version_files` and regenerate `CHANGELOG.md`.
-
-Commitizen deliberately bundles a new release into a single commit.
-This is core to its philosophy: the version should live in the code itself, not only in a Git tag,
-so anyone can read the current version straight from the source, without needing to inspect the tags.
-When a Git tag is the sole source of truth, that guarantee disappears,
-the version becomes metadata layered on top of your history instead of something visible within the code itself.
-
-## Github action example
+## GitHub Action Example
 
 ```yaml title=".github/workflows/bump-version.yml"
 name: Bump version
@@ -66,6 +60,23 @@ jobs:
       - id: bump-version
         run: |
           next_version=$(cz version --project --next --tag)
-          git tag --annotate "$next_version" --message "$next_version"
+          cz changelog --incremental --dry-run --unreleased-version "$next_version" > .changelog.md
+          git tag --annotate "$next_version" -F .changelog.md
           git push --follow-tags
 ```
+
+## Why Can't I Bump with SCM?
+
+When you run `cz bump`, Commitizen normally creates a new commit that updates the version somewhere,
+either in `.cz.toml`, or in `pyproject.toml` if you're using Python, or `Cargo.toml` for rust.
+It may also update `version_files` and regenerate `CHANGELOG.md`.
+
+Commitizen deliberately bundles a new release into a single "release commit".
+
+This is core to its philosophy: the version should live in the code itself, not only in a Git tag,
+so anyone can read the current version straight from the source, without needing to inspect the tags.
+
+When a Git tag is the sole source of truth, that guarantee disappears,
+the version becomes metadata layered on top of your history instead of something visible within the code itself.
+
+Nonetheless, you can still do it.