diff --git a/commitizen/cli.py b/commitizen/cli.py
index c11e9078d..57732ee4d 100644
--- a/commitizen/cli.py
+++ b/commitizen/cli.py
@@ -208,6 +208,11 @@ def __call__(
                     {
                         "name": "--files-only",
                         "action": "store_true",
+                        "help": "Bump version in config files (deprecated; use --version-files-only).",
+                    },
+                    {
+                        "name": "--version-files-only",
+                        "action": "store_true",
                         "help": "bump version in the files from the config",
                     },
                     {
diff --git a/commitizen/commands/bump.py b/commitizen/commands/bump.py
index 3dc678920..11d65fde0 100644
--- a/commitizen/commands/bump.py
+++ b/commitizen/commands/bump.py
@@ -47,6 +47,7 @@ class BumpArgs(Settings, total=False):
     dry_run: bool
     file_name: str
     files_only: bool | None
+    version_files_only: bool | None
     get_next: bool
     git_output_to_stderr: bool
     increment_mode: str
@@ -356,9 +357,17 @@ def __call__(self) -> None:
                 else None,
             )
 
-        if self.arguments["files_only"]:
+        if self.arguments.get("files_only"):
+            warnings.warn(
+                "--files-only is deprecated and will be removed in v5. Use --version-files-only instead.",
+                DeprecationWarning,
+            )
             raise ExpectedExit()
 
+        if self.arguments.get("version_files_only"):
+            raise ExpectedExit()
+
+
         # FIXME: check if any changes have been staged
         git.add(*files)
         c = git.commit(message, args=self._get_commit_args())
diff --git a/docs/commands/bump.md b/docs/commands/bump.md
index 510fb4619..3c277da58 100644
--- a/docs/commands/bump.md
+++ b/docs/commands/bump.md
@@ -2,9 +2,18 @@
 
 ## About
 
-`cz bump` is a powerful command that **automatically** determines and increases your project's version number based on your commit history. It analyzes your commits to determine the appropriate version increment according to semantic versioning principles.
+`cz bump` is a powerful command that **automatically** determines and increases your project's version number based on your commit history.
 
-### Key Features
+It analyzes your commits to determine the appropriate version increment according to semantic versioning principles.
+
+!!! note
+    In the following documentation, the term "configuration file" refers to `pyproject.toml`, `.cz.toml` or other configuration files.
+
+    We will use `pyproject.toml` as the configuration file throughout the documentation.
+
+    See [Configuration file](../config.md#configuration-file) for more details.
+
+## Key Features
 
 - **Automatic Version Detection**: Analyzes commit history to determine the appropriate version bump
 - **Manual Version Control**: Supports manual version specification when needed
@@ -21,7 +30,7 @@ The version follows the `MAJOR.MINOR.PATCH` format, with increments determined b
 | `MINOR`   | New features                | `feat`                  |
 | `PATCH`   | Fixes and improvements      | `fix`, `perf`, `refactor`|
 
-### Version Schemes
+### Version Schemes (`--version-scheme`)
 
 By default, Commitizen uses [PEP 440][pep440] for version formatting. You can switch to semantic versioning using either:
 
@@ -36,6 +45,26 @@ cz bump --version-scheme semver
 version_scheme = "semver"
 ```
 
+Available options are:
+
+- `pep440`: [PEP 440][pep440] (**default** and recommended for Python projects)
+- `semver`: [Semantic Versioning][semver] (recommended for non-Python projects)
+
+You can also set this in the [configuration](#version_scheme) with `version_scheme = "semver"`.
+
+!!! note
+    [pep440][pep440] and [semver][semver] are quite similar, although their difference lies in
+    how the prereleases look. For example, `0.3.1a0` in pep440 is equivalent to `0.3.1-a0` in semver.
+
+    The following table illustrates the difference between the two schemes:
+
+    | Version Type | pep440         | semver          |
+    |--------------|----------------|-----------------|
+    | Non-prerelease | `0.1.0`        | `0.1.0`         |
+    | Prerelease     | `0.3.1a0`      | `0.3.1-a0`      |
+    | Devrelease     | `0.1.1.dev1`   | `0.1.1-dev1`    |
+    | Dev and pre    | `1.0.0a3.dev1` | `1.0.0-a3-dev1` |
+
 ### PEP440 Version Examples
 
 Commitizen supports the [PEP 440][pep440] version format, which includes several version types. Here are examples of each:
@@ -76,21 +105,31 @@ Commitizen supports the [PEP 440][pep440] version format, which includes several
 
 > **Note**: `post` releases (e.g., `1.0.0.post1`) are not currently supported.
 
-## Usage
+## Command line options
 
 ![cz bump --help](../images/cli_help/cz_bump___help.svg)
 
-### `--files-only`
+### `--files-only` (deprecated)
+**Deprecated**: This flag will be removed in Commitizen v5.  
+Please use [`--version-files-only`](#--version-files-only) instead.
 
-Bumps the version in the files defined in `version_files` without creating a commit and tag on the git repository,
+Bumps the version in the files defined in [`version_files`](#version_files) without creating a commit and tag on the git repository,
 
 ```bash
 cz bump --files-only
 ```
 
+### `--version-files-only`
+
+Bumps the version in the files defined in [`version_files`](#version_files) without creating a commit and tag on the git repository,
+
+```bash
+cz bump --version-files-only
+```
+
 ### `--changelog`
 
-Generate a **changelog** along with the new version and tag when bumping.
+Generate a **changelog** along with the new version and tag when bumping. See [changelog](./changelog.md) for more details.
 
 ```bash
 cz bump --changelog
@@ -122,16 +161,21 @@ by their precedence and showcase how a release might flow through a development
 
 ### `--increment-mode`
 
-By default, `--increment-mode` is set to `linear`, which ensures that bumping pre-releases _maintains linearity_:
-bumping of a pre-release with lower precedence than the current pre-release phase maintains the current phase of
-higher precedence. For example, if the current version is `1.0.0b1` then bumping with `--prerelease alpha` will
-continue to bump the "beta" phase.
+#### `--increment-mode=linear` (default)
+
+Ensures that bumping pre-releases **maintains linearity**.
+
+Bumping a pre-release with lower precedence than the current pre-release phase maintains the current phase of higher precedence.
+For example, if the current version is `1.0.0b1` then bumping with `--prerelease alpha` will continue to bump the *beta* phase.
+
+#### `--increment-mode=exact`
 
-Setting `--increment-mode` to `exact` instructs `cz bump` to instead apply the
-exact changes that have been specified with `--increment` or determined from the commit log. For example,
-`--prerelease beta` will always result in a `b` tag, and `--increment PATCH` will always increase the patch component.
+Applies the exact changes that have been specified with `--increment` or determined from the commit log.
+For example, `--prerelease beta` will always result in a `b` tag, and `--increment PATCH` will always increase the patch component.
 
-Below are some examples that illustrate the difference in behavior:
+#### Examples
+
+The following table illustrates the difference in behavior between the two modes:
 
 | Increment | Pre-release | Start Version | `--increment-mode=linear` | `--increment-mode=exact` |
 |-----------|-------------|---------------|---------------------------|--------------------------|
@@ -144,14 +188,13 @@ Below are some examples that illustrate the difference in behavior:
 
 ### `--check-consistency`
 
-Check whether the versions defined in `version_files` and the version in Commitizen
-configuration are consistent before bumping version.
+Check whether the versions defined in [`version_files`](#version_files) and the version in Commitizen configuration are consistent before bumping version.
 
 ```bash
 cz bump --check-consistency
 ```
 
-For example, if we have `pyproject.toml`
+For example, if we have the following configuration file `pyproject.toml`:
 
 ```toml title="pyproject.toml"
 [tool.commitizen]
@@ -162,67 +205,94 @@ version_files = [
 ]
 ```
 
-`src/__version__.py`
-
+and the following version files `src/__version__.py` and `setup.py`:
 
 ```python title="src/__version__.py"
 __version__ = "1.21.0"
 ```
 
-and `setup.py`
-
 ```python title="setup.py"
 from setuptools import setup
 
 setup(..., version="1.0.5", ...)
 ```
 
-If `--check-consistency` is used, Commitizen will check whether the current version in `pyproject.toml`
-exists in all version_files and find out it does not exist in `setup.py` and fails.
-However, it will still update `pyproject.toml` and `src/__version__.py`.
+When you run `cz bump --check-consistency`, Commitizen will verify that the current version in `pyproject.toml` (`1.21.0`) exists in all files listed in [`version_files`](#version_files).
+In this example, it will detect that `setup.py` contains `1.0.5` instead of `1.21.0`, causing the bump to fail.
+
+!!! warning "Partial updates on failure"
+    If the consistency check fails, Commitizen may have already updated some files (like `pyproject.toml` and `src/__version__.py`) before detecting the inconsistency.
+    In this case, you'll need to restore the files to their previous state.
+
+    To resolve this issue:
+
+    1. Restore the modified files to their previous state:
+      ```bash
+      git checkout .
+      ```
+
+    2. Manually update the version in `setup.py` to match the version in `pyproject.toml`:
+      ```python title="setup.py"
+      from setuptools import setup
 
-To fix it, you'll first `git checkout .` to reset to the status before trying to bump and update
-the version in `setup.py` to `1.21.0`
+      setup(..., version="1.21.0", ...)
+      ```
+
+    3. Run the bump command again:
+      ```bash
+      cz bump --check-consistency
+      ```
 
 ### `--local-version`
 
 Bump the local portion of the version.
 
-```bash
-cz bump --local-version
-```
-
-For example, if we have `pyproject.toml`
+For example, if we have the following configuration file `pyproject.toml`:
 
 ```toml title="pyproject.toml"
 [tool.commitizen]
 version = "5.3.5+0.1.0"
 ```
 
-If `--local-version` is used, it will bump only the local version `0.1.0` and keep the public version `5.3.5` intact, bumping to the version `5.3.5+0.2.0`.
+When you run `cz bump --local-version`, it will bump only the local version `0.1.0` and keep the public version `5.3.5` intact, bumping to the version `5.3.5+0.2.0`.
 
 ### `--annotated-tag`
 
-If `--annotated-tag` is used, Commitizen will create annotated tags. It is also available via configuration, in `pyproject.toml` or `.cz.toml`.
+Create annotated tags.
+
+It is also available via configuration files.
+
+For example, in `pyproject.toml`:
+
+```toml title="pyproject.toml"
+[tool.commitizen]
+annotated_tag = true
+```
 
 ### `--annotated-tag-message`
 
-If `--annotated-tag-message` is used, Commitizen will create annotated tags with the given message.
+Create annotated tags with the given message.
+
+It is also available via configuration files.
+
+For example, in `pyproject.toml`:
+
+```toml title="pyproject.toml"
+[tool.commitizen]
+annotated_tag_message = "Annotated tag message"
+```
 
 ### `--changelog-to-stdout`
 
-If `--changelog-to-stdout` is used, the incremental changelog generated by the bump
-will be sent to the stdout, and any other message generated by the bump will be
-sent to stderr.
+Send the incremental changelog generated by `cz bump` to `stdout`.
+Any other messages generated by `cz bump` will be sent to `stderr`.
 
-If `--changelog` is not used with this command, it is still smart enough to
-understand that the user wants to create a changelog. It is recommended to be
-explicit and use `--changelog` (or the setting `update_changelog_on_bump`).
+When this flag is used, `--changelog` is implied.
+However, it is recommended to set `--changelog` (or the setting `update_changelog_on_bump`) explicitly when the option `--changelog-to-stdout` is used.
 
-This command is useful to "transport" the newly created changelog.
-It can be sent to an auditing system, or to create a GitHub Release.
+#### Useful scenarios
 
-Example:
+This is useful to pipe the newly created changelog to another tool. For example, it can be sent to an auditing system, or to create a GitHub Release, etc.
 
 ```bash
 cz bump --changelog --changelog-to-stdout > body.md
@@ -230,55 +300,64 @@ cz bump --changelog --changelog-to-stdout > body.md
 
 ### `--git-output-to-stderr`
 
-If `--git-output-to-stderr` is used, git commands output is redirected to stderr.
+If `--git-output-to-stderr` is used, git commands output is redirected to `stderr`.
+
+Useful when used with `--changelog-to-stdout` and piping the output to a file,
 
-This command is useful when used with `--changelog-to-stdout` and piping the output to a file,
-and you don't want the `git commit` output polluting  the stdout.
+For example, `git commit` output may pollute `stdout`, so it is recommended to use this flag when piping the output to a file.
 
 ### `--retry`
 
-If you use tools like [pre-commit](https://pre-commit.com/), add this flag.
-It will retry the commit if it fails the 1st time.
+If you use tools like [pre-commit](https://pre-commit.com/), you can add this flag.
+It will retry the commit if it fails the first time.
 
 Useful to combine with code formatters, like [Prettier](https://prettier.io/).
 
 ### `--major-version-zero`
 
-A project in its initial development should have a major version zero, and even breaking changes
-should not bump that major version from zero. This command ensures that behavior.
+Breaking changes does not bump the major version number.
 
-If `--major-version-zero` is used for projects that have a version number greater than zero it fails.
-If used together with a manual version the command also fails.
+Say you have a project with the version `0.1.x` and you commit a breaking change like this:
 
-We recommend setting `major_version_zero = true` in your configuration file while a project
-is in its initial development. Remove that configuration using a breaking-change commit to bump
-your project's major version to `v1.0.0` once your project has reached maturity.
+```text
+fix(magic)!: fully deprecate whatever
+```
 
-### `--version-scheme`
+and you run
 
-Choose the version format, options: `pep440`, `semver`.
+```bash
+cz bump --major-version-zero
+```
 
-Default: `pep440`
+Then the version of your project will be bumped to `0.2.0` instead of `1.0.0`.
 
-Recommended for python: `pep440`
+!!! note
+    A project in its initial development should have a major version zero,
+    and even breaking changes should not bump that major version from zero. This command ensures that behavior.
 
-Recommended for other: `semver`
+    We recommend setting `major_version_zero = true` in your configuration file while a project
+    is in its initial development. Remove that configuration using a breaking-change commit to bump
+    your project's major version to `v1.0.0` once your project has reached maturity.
 
-You can also set this in the [configuration](#version_scheme) with `version_scheme = "semver"`.
+!!! warning
+    This option is only compatible with projects that have major version number zero, `0.x.x` for example.
 
-[pep440][pep440] and [semver][semver] are quite similar, their difference lies in
-how the prereleases look.
+    It fails when used with projects that have a version number greater than zero like `1.x.x`.
 
-| schemes        | pep440         | semver          |
-| -------------- | -------------- | --------------- |
-| non-prerelease | `0.1.0`        | `0.1.0`         |
-| prerelease     | `0.3.1a0`      | `0.3.1-a0`      |
-| devrelease     | `0.1.1.dev1`   | `0.1.1-dev1`    |
-| dev and pre    | `1.0.0a3.dev1` | `1.0.0-a3-dev1` |
+    If used together with a manual version, the command also fails.
 
-Can I transition from one to the other?
+    ```bash
+    # This fails
+    cz bump 0.1.0 --major-version-zero
+    ```
 
-Yes, you shouldn't have any issues.
+### `--gpg-sign`
+
+Create gpg signed tags.
+
+```bash
+cz bump --gpg-sign
+```
 
 ### `--template`
 
@@ -304,15 +383,23 @@ cz bump --build-metadata yourmetadata
 ```
 
 Will create a version like `1.1.2+yourmetadata`.
+
 This can be useful for multiple things
+
 - Git hash in version
 - Labeling the version with additional metadata.
 
-Note that Commitizen ignores everything after `+` when it bumps the version. It is therefore safe to write different build-metadata between versions.
+!!! note
+    Commitizen ignores everything after `+` when it bumps the version.
+
+    It is therefore safe to write different build-metadata between versions.
+
+
+!!! warning
+    Normally, you should not use this functionality, but if you decide to do so, keep in mind that:
 
-You should normally not use this functionality, but if you decide to do, keep in mind that
-- 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.
+    - 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.
 
 ### `--get-next`
 
@@ -323,33 +410,33 @@ and `manual version`.
 cz bump --get-next
 ```
 
-Will output the next version, e.g., `1.2.3`. This can be useful for determining the next version based on CI for non
-production environments/builds.
+Will only output the next version, e.g., `1.2.3`. This can be useful for determining the next version based on CI for non-production environments/builds.
 
-This behavior differs from the `--dry-run` flag. The `--dry-run` flag provides a more detailed output and can also show
-the changes as they would appear in the changelog file.
+!!! note "Compare with `--dry-run`"
+    `--dry-run` provides a more detailed output including the changes as they would appear in the changelog file, while `--get-next` only outputs the next version.
 
-The following output is the result of `cz bump --dry-run`:
+    The following is the output of `cz bump --dry-run`:
 
-```
-bump: version 3.28.0 → 3.29.0
-tag to create: v3.29.0
-increment detected: MINOR
-```
+    ```text
+    bump: version 3.28.0 → 3.29.0
+    tag to create: v3.29.0
+    increment detected: MINOR
+    ```
 
-The following output is the result of `cz bump --get-next`:
+    The following is the output of `cz bump --get-next`:
 
-```
-3.29.0
-```
+    ```text
+    3.29.0
+    ```
 
-The `--get-next` flag will raise a `NoneIncrementExit` if the found commits are not eligible for a version bump.
+!!! warning
+    The `--get-next` flag will raise a `NoneIncrementExit` if the found commits are not eligible for a version bump.
 
-For information on how to suppress this exit, see [avoid raising errors](#avoid-raising-errors).
+    For information on how to suppress this exit, see [avoid raising errors](#avoid-raising-errors).
 
 ### `--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]`
+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 `[MANUAL_VERSION]`
 
 ```sh
 # bump a minor version even when there's only bug fixes, documentation changes or even no commits
@@ -359,74 +446,15 @@ cz bump --incremental MINOR --allow-no-commit
 cz bump --allow-no-commit 2.0.0
 ```
 
-## Avoid raising errors
-
-Some situations from Commitizen raise an exit code different from 0.
-If the error code is different from 0, any CI or script running Commitizen might be interrupted.
-
-If you have a special use case, where you don't want to raise one of this error codes, you can
-tell Commitizen to not raise them.
-
-### Recommended use case
-
-At the moment, we've identified that the most common error code to skip is
-
-| Error name        | Exit code |
-| ----------------- | --------- |
-| NoneIncrementExit | 21        |
-
-There are some situations where you don't want to get an error code when some
-commits do not match your rules, you just want those commits to be skipped.
-
-```sh
-cz -nr 21 bump
-```
-
-### Easy way
-
-Check which error code was raised by Commitizen by running in the terminal
-
-```sh
-echo $?
-```
-
-The output should be an integer like this
-
-```sh
-3
-```
-
-And then you can tell Commitizen to ignore it:
-
-```sh
-cz --no-raise 3
-```
-
-You can tell Commitizen to skip more than one if needed:
-
-```sh
-cz --no-raise 3,4,5
-```
-
-### Longer way
-
-Check the list of [exit_codes](../exit_codes.md) and understand which one you have
-to skip and why.
-
-Remember to document somewhere this, because you'll forget.
-
-For example if the system raises a `NoneIncrementExit` error, you look it up
-on the list, and then you can use the exit code:
+### `--version-scheme`
 
-```sh
-cz -nr 21 bump
-```
+See [Version Schemes](#version-schemes-version-scheme).
 
-## Configuration
+## Configuration file options
 
 ### `tag_format`
 
-`tag_format` and `version_scheme` are combined to make Git tag names from versions.
+`tag_format` and [`version_scheme`](#version-schemes-version-scheme) are combined to make Git tag names from versions.
 
 These are used in:
 
@@ -438,7 +466,7 @@ These are used in:
   - If `tag_format` is set to `$version` (default): `VersionProtocol.parser` (allows `v` prefix)
   - If `tag_format` is set: Custom regex similar to SemVer (not as lenient as PEP440 e.g. on dev-releases)
 
-Commitizen supports 2 types of formats, a simple and a more complex.
+Commitizen supports two types of formats, a simple and a more complex.
 
 ```bash
 cz bump --tag-format="v$version"
@@ -448,7 +476,7 @@ cz bump --tag-format="v$version"
 cz bump --tag-format="v$minor.$major.$patch$prerelease.$devrelease"
 ```
 
-In your `pyproject.toml` or `.cz.toml`
+In your configuration file:
 
 ```toml
 [tool.commitizen]
@@ -461,46 +489,86 @@ Supported variables:
 
 | Variable                       | Description                                 |
 |--------------------------------|---------------------------------------------|
-| `$version`, `${version}`       | full generated version                      |
+| `$version`, `${version}`       | fully generated version                      |
 | `$major`, `${major}`           | MAJOR increment                             |
 | `$minor`, `${minor}`           | MINOR increment                             |
 | `$patch`, `${patch}`           | PATCH increment                             |
 | `$prerelease`, `${prerelease}` | Prerelease (alpha, beta, release candidate) |
 | `$devrelease`, ${devrelease}`  | Development release                         |
 
----
+### `version_files`
 
-### `version_files` \*
+Identify the files or glob patterns which should be updated with the new version.
 
-It is used to identify the files or glob patterns which should be updated with the new version.
-It is also possible to provide a pattern for each file, separated by colons (`:`).
-
-Commitizen will update its configuration file automatically (`pyproject.toml`, `.cz`) when bumping,
+Commitizen will update its configuration file automatically when bumping,
 regarding if the file is present or not in `version_files`.
 
-\* Renamed from `files` to `version_files`.
+You may specify the `version_files` in your configuration file.
+
+```toml title="pyproject.toml"
+[tool.commitizen]
+version_files = [
+    "src/__version__.py",
+]
+```
+
+It is also possible to provide a pattern for each file, separated by a colon (e.g. `file:pattern`). See the below example for more details.
+
+```toml title="pyproject.toml"
+[tool.commitizen]
+version_files = [
+    "packages/*/pyproject.toml:version",
+    "setup.json:version",
+]
+```
 
-Some examples
+#### Example scenario
 
-`pyproject.toml`, `.cz.toml` or `cz.toml`
+We have a project with the following configuration file `pyproject.toml`:
 
 ```toml title="pyproject.toml"
 [tool.commitizen]
 version_files = [
     "src/__version__.py",
     "packages/*/pyproject.toml:version",
-    "setup.py:version",
+    "setup.json:version",
 ]
 ```
 
-In the example above, we can see the reference `"setup.py:version"`.
-This means that it will find a file `setup.py` and will only make a change
-in a line containing the `version` substring.
+For the reference `"setup.json:version"`, it means that it will look for a file `setup.json` and will only change the lines that contain the substring `"version"`.
+
+For example, if the content of `setup.json` is:
+
+<!-- DEPENDENCY: repeated_version_number.json -->
+
+```json title="setup.json"
+{
+  "name": "magictool",
+  "version": "1.2.3",
+  "dependencies": {
+      "lodash": "1.2.3"
+  }
+}
+```
+
+After running `cz bump 2.0.0`, its content will be updated to:
+
+```diff title="setup.json"
+{
+  "name": "magictool",
+- "version": "1.2.3",
++ "version": "2.0.0",
+  "dependencies": {
+      "lodash": "1.2.3"
+  }
+}
+```
 
 !!! note
     Files can be specified using relative (to the execution) paths, absolute paths, or glob patterns.
 
----
+!!! note "Historical note"
+    This option was renamed from `files` to `version_files`.
 
 ### `bump_message`
 
@@ -513,69 +581,52 @@ Defaults to: `bump: version $current_version → $new_version`
 | `$current_version` | the version existing before bumping |
 | `$new_version`     | version generated after bumping     |
 
-Some examples
-
-`pyproject.toml`, `.cz.toml` or `cz.toml`
+#### Example configuration
 
 ```toml title="pyproject.toml"
 [tool.commitizen]
 bump_message = "release $current_version → $new_version [skip-ci]"
 ```
 
----
-
 ### `update_changelog_on_bump`
 
-When set to `true` the changelog is always updated incrementally when running `cz bump`, so the user does not have to provide the `--changelog` flag every time.
-
-Defaults to: `false`
+When set to `true`, `cz bump` is equivalent to `cz bump --changelog`.
 
 ```toml title="pyproject.toml"
 [tool.commitizen]
 update_changelog_on_bump = true
 ```
 
----
-
 ### `annotated_tag`
 
-When set to `true`, Commitizen will create annotated tags.
+When set to `true`, `cz bump` is equivalent to `cz bump --annotated-tag`.
 
 ```toml title="pyproject.toml"
 [tool.commitizen]
 annotated_tag = true
 ```
 
----
-
 ### `gpg_sign`
 
-When set to `true`, Commitizen will create gpg signed tags.
+When set to `true`, `cz bump` is equivalent to `cz bump --gpg-sign`. See [--gpg-sign](#-gpg-sign).
 
 ```toml title="pyproject.toml"
 [tool.commitizen]
 gpg_sign = true
 ```
 
----
-
 ### `major_version_zero`
 
-When set to `true`, Commitizen will keep the major version at zero.
-Useful during the initial development stage of your project.
-
-Defaults to: `false`
+When set to `true`, `cz bump` is equivalent to `cz bump --major-version-zero`. See [--major-version-zero](#-major-version-zero).
 
 ```toml title="pyproject.toml"
 [tool.commitizen]
 major_version_zero = true
 ```
 
----
-
 ### `pre_bump_hooks`
 
-A list of optional commands that will run right _after_ updating `version_files`
+A list of optional commands that will run right _after_ updating [`version_files`](#version_files)
 and _before_ actual committing and tagging the release.
 
 Useful when you need to generate documentation based on the new version. During
@@ -599,8 +650,6 @@ pre_bump_hooks = [
 ]
 ```
 
----
-
 ### `post_bump_hooks`
 
 A list of optional commands that will run right _after_ committing and tagging the release.
@@ -639,22 +688,69 @@ prerelease_offset = 1
 
 ### `version_scheme`
 
-Choose version scheme
+See [Version Schemes](#version-schemes-version-scheme).
 
-| schemes        | pep440         | semver          | semver2               |
-| -------------- | -------------- | --------------- | --------------------- |
-| non-prerelease | `0.1.0`        | `0.1.0`         | `0.1.0`               |
-| prerelease     | `0.3.1a0`      | `0.3.1-a0`      | `0.3.1-alpha.0`       |
-| devrelease     | `0.1.1.dev1`   | `0.1.1-dev1`    | `0.1.1-dev.1`         |
-| dev and pre    | `1.0.0a3.dev1` | `1.0.0-a3-dev1` | `1.0.0-alpha.3.dev.1` |
+## Avoid raising errors
 
-Options: `pep440`, `semver`, `semver2`
+Some situations from Commitizen raise an exit code different from 0.
+If the error code is different from 0, any CI or script running Commitizen might be interrupted.
 
-Defaults to: `pep440`
+If you have a special use case, where you don't want to raise one of this error codes, you can
+tell Commitizen to not raise them.
 
-```toml title="pyproject.toml"
-[tool.commitizen]
-version_scheme = "semver"
+### Recommended use case
+
+At the moment, we've identified that the most common error code to skip is
+
+| Error name        | Exit code |
+| ----------------- | --------- |
+| NoneIncrementExit | 21        |
+
+There are some situations where you don't want to get an error code when some
+commits do not match your rules, you just want those commits to be skipped.
+
+```sh
+cz -nr 21 bump
+```
+
+### Easy way
+
+Check which error code was raised by Commitizen by running in the terminal
+
+```sh
+echo $?
+```
+
+The output should be an integer like this
+
+```sh
+3
+```
+
+And then you can tell Commitizen to ignore it:
+
+```sh
+cz --no-raise 3
+```
+
+You can tell Commitizen to skip more than one if needed:
+
+```sh
+cz --no-raise 3,4,5
+```
+
+### Longer way
+
+Check the list of [exit_codes](../exit_codes.md) and understand which one you have
+to skip and why.
+
+Remember to document somewhere this, because you'll forget.
+
+For example if the system raises a `NoneIncrementExit` error, you look it up
+on the list, and then you can use the exit code:
+
+```sh
+cz -nr 21 bump
 ```
 
 ## Custom bump
diff --git a/docs/config.md b/docs/config.md
index 94aa2076b..a3e317988 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -408,7 +408,7 @@ setup(
 [prerelease-offset]: commands/bump.md#prerelease_offset
 [retry_after_failure]: commands/commit.md#retry
 [allow_abort]: commands/check.md#allow-abort
-[version-scheme]: commands/bump.md#-version-scheme
+[version-scheme]: commands/bump.md#version-schemes-version-scheme
 [pre_bump_hooks]: commands/bump.md#pre_bump_hooks
 [post_bump_hooks]: commands/bump.md#post_bump_hooks
 [allowed_prefixes]: commands/check.md#allowed-prefixes
diff --git a/tests/commands/test_bump_command.py b/tests/commands/test_bump_command.py
index 59297b172..67f36d78b 100644
--- a/tests/commands/test_bump_command.py
+++ b/tests/commands/test_bump_command.py
@@ -555,7 +555,7 @@ def test_bump_files_only(mocker: MockFixture, tmp_commitizen_project):
     assert tag_exists is True
 
     create_file_and_commit("feat: another new feature")
-    testargs = ["cz", "bump", "--yes", "--files-only"]
+    testargs = ["cz", "bump", "--yes", "--files-only","--version-files-only"]
     mocker.patch.object(sys, "argv", testargs)
     with pytest.raises(ExpectedExit):
         cli.main()
@@ -1427,7 +1427,7 @@ def test_bump_changelog_contains_increment_only(mocker, tmp_commitizen_project,
     # Add a commit and create the incremental changelog to v3.0.0
     # it should only include v3 changes
     create_file_and_commit("feat(next)!: next version")
-    testargs = ["cz", "bump", "--yes", "--files-only", "--changelog-to-stdout"]
+    testargs = ["cz", "bump", "--yes", "--files-only", "--version-files-only", "--changelog-to-stdout"]
     mocker.patch.object(sys, "argv", testargs)
     with pytest.raises(ExpectedExit):
         cli.main()
diff --git a/tests/commands/test_bump_command/test_bump_command_shows_description_when_use_help_option.txt b/tests/commands/test_bump_command/test_bump_command_shows_description_when_use_help_option.txt
index 4cf8e6c91..cff936e9e 100644
--- a/tests/commands/test_bump_command/test_bump_command_shows_description_when_use_help_option.txt
+++ b/tests/commands/test_bump_command/test_bump_command_shows_description_when_use_help_option.txt
@@ -1,4 +1,4 @@
-usage: cz bump [-h] [--dry-run] [--files-only] [--local-version] [--changelog]
+usage: cz bump [-h] [--dry-run] [--files-only] [--version-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}]
@@ -22,7 +22,8 @@ positional arguments:
 options:
   -h, --help            show this help message and exit
   --dry-run             show output to stdout, no commit, no modified files
-  --files-only          bump version in the files from the config
+  --files-only          bump version in the files from the config (Deprecated in v5)
+  --version-files-only  bump version in the files from the config 
   --local-version       bump only the local version portion
   --changelog, -ch      generate the changelog for the newest version
   --no-verify           this option bypasses the pre-commit and commit-msg