From 0999ef691ccf65697bb9951333891359b342a9d3 Mon Sep 17 00:00:00 2001
From: Wei Lee <weilee.rx@gmail.com>
Date: Sun, 21 Apr 2024 17:14:17 +0800
Subject: [PATCH] docs(bump): add description for bump "--allow-no-commit"
 argument

---
 docs/bump.md | 46 ++++++++++++++++++++++++++++++++++------------
 1 file changed, 34 insertions(+), 12 deletions(-)

diff --git a/docs/bump.md b/docs/bump.md
index 6dad38219e..a0b580a1ef 100644
--- a/docs/bump.md
+++ b/docs/bump.md
@@ -54,8 +54,10 @@ Some examples of pep440:
 $ cz bump --help
 usage: cz bump [-h] [--dry-run] [--files-only] [--local-version] [--changelog] [--no-verify] [--yes] [--tag-format TAG_FORMAT]
                [--bump-message BUMP_MESSAGE] [--prerelease {alpha,beta,rc}] [--devrelease DEVRELEASE] [--increment {MAJOR,MINOR,PATCH}]
-               [--check-consistency] [--annotated-tag] [--gpg-sign] [--changelog-to-stdout] [--git-output-to-stderr] [--retry] [--major-version-zero]
-               [--prerelease-offset PRERELEASE_OFFSET] [--version-scheme {pep440,semver,semver2}] [--version-type {pep440,semver,semver2}] [--build-metadata BUILD_METADATA]
+               [--increment-mode {linear,exact}] [--check-consistency] [--annotated-tag] [--annotated-tag-message ANNOTATED_TAG_MESSAGE]
+               [--gpg-sign] [--changelog-to-stdout] [--git-output-to-stderr] [--retry] [--major-version-zero] [--template TEMPLATE]
+               [--extra EXTRA] [--file-name FILE_NAME] [--prerelease-offset PRERELEASE_OFFSET] [--version-scheme {pep440,semver2,semver}]
+               [--version-type {pep440,semver2,semver}] [--build-metadata BUILD_METADATA] [--allow-no-commit]
                [MANUAL_VERSION]
 
 positional arguments:
@@ -79,15 +81,16 @@ options:
                         specify non-negative integer for dev. release
   --increment {MAJOR,MINOR,PATCH}
                         manually specify the desired increment
-  --increment-mode
-                        set the method by which the new version is chosen. 'linear' (default) guesses the next version based
-                        on typical linear version progression, such that bumping of a pre-release with lower precedence than
-                        the current pre-release phase maintains the current phase of higher precedence. 'exact' applies the
-                        changes that have been specified (or determined from the commit log) without interpretation, such that
-                        the increment and pre-release are always honored
+  --increment-mode {linear,exact}
+                        set the method by which the new version is chosen. 'linear' (default) guesses the next version based on typical
+                        linear version progression, such that bumping of a pre-release with lower precedence than the current pre-release
+                        phase maintains the current phase of higher precedence. 'exact' applies the changes that have been specified (or
+                        determined from the commit log) without interpretation, such that the increment and pre-release are always honored
   --check-consistency, -cc
                         check consistency among versions defined in commitizen configuration and version_files
   --annotated-tag, -at  create annotated tag instead of lightweight one
+  --annotated-tag-message ANNOTATED_TAG_MESSAGE, -atm ANNOTATED_TAG_MESSAGE
+                        create annotated tag message
   --gpg-sign, -s        sign tag instead of lightweight one
   --changelog-to-stdout
                         Output changelog to the stdout
@@ -95,14 +98,21 @@ options:
                         Redirect git output to stderr
   --retry               retry commit if it fails the 1st time
   --major-version-zero  keep major version at zero, even for breaking changes
+  --template TEMPLATE, -t TEMPLATE
+                        changelog template file name (relative to the current working directory)
+  --extra EXTRA, -e EXTRA
+                        a changelog extra variable (in the form 'key=value')
+  --file-name FILE_NAME
+                        file name of changelog (default: 'CHANGELOG.md')
   --prerelease-offset PRERELEASE_OFFSET
                         start pre-releases with this offset
-  --version-scheme {pep440,semver,semver2}
+  --version-scheme {pep440,semver2,semver}
                         choose version scheme
-  --version-type {pep440,semver,semver2}
+  --version-type {pep440,semver2,semver}
                         Deprecated, use --version-scheme
-  --build-metadata {BUILD_METADATA}
-                        additional metadata in the version string
+  --build-metadata BUILD_METADATA
+                        Add additional build-metadata to the version-number
+  --allow-no-commit     bump version without eligible commits
 ```
 
 ### `--files-only`
@@ -337,6 +347,18 @@ You should normally not use this functionality, but if you decide to do, keep in
 * Version `1.2.3+a`, and `1.2.3+b` are the same version! Tools should not use the string after `+` for version calculation. This is probably not a guarantee (example in helm) even tho it is in the spec.
 * It might be problematic having the metadata in place when doing upgrades depending on what tool you use.
 
+### `--allow-no-commit`
+
+Allow the project version to be bumped even when there's no eligible version. This is most useful when used with `--increment {MAJOR,MINOR,PATCH}` or `[MANUL_VERSION]`
+
+```sh
+# bump a minor version even when there's only bug fixes, documentation changes or even no commits
+cz bump --incremental MINOR --allow-no-commit
+
+# bump version to 2.0.0 even when there's no breaking changes changes or even no commits
+cz bump --allow-no-commit 2.0.0
+```
+
 ## Avoid raising errors
 
 Some situations from commitizen raise an exit code different than 0.