Updated documentation

docsrc/changelog.md

@@ -0,0 +1,2 @@
+```{include} ../CHANGELOG.md
+```

docsrc/index.md

@@ -8,6 +8,8 @@ caption: Contents
 Introduction <readme>
 usage
 configuration
+version-parts
+search-and-replace
 cli
 api
 contributing

docsrc/search-and-replace.md

@@ -2,49 +2,43 @@
 
 Given this `requirements.txt`:
 
-  Django>=1.5.6,<1.6
-  MyProject==1.5.6
+```text
+Django>=1.5.6,<1.6
+MyProject==1.5.6
+```
 
-using this `.bumpversion.cfg` will ensure only the line containing
-`MyProject` will be changed:
+using this `.bumpversion.toml` will ensure only the line containing `MyProject` will be changed:
 
-```ini
-[bumpversion]
-current_version = 1.5.6
+```toml
+[tool.bumpversion]
+current_version = "1.5.6"
 
-[bumpversion:file:requirements.txt]
-search = MyProject=={current_version}
-replace = MyProject=={new_version}
+[[tool.bumpversion:files]]
+filename = "requirements.txt"
+search = "MyProject=={current_version}"
+replace = "MyProject=={new_version}"
 ```
 
-Can be multiple lines, templated using [Python Format String Syntax](https://docs.python.org/3/library/string.html#format-string-syntax).
-
-**NOTE**: (*Updated in v1.0.1*) It is important to point out that if a
-custom search pattern is configured, then `bump-my-version` will only perform
-a change if it finds an exact match and will not fallback to the default
-pattern. This is to prevent accidentally changing strings that match the
-default pattern when there is a typo in the custom search pattern.
+It can be multiple lines, templated using [Python Format String Syntax](https://docs.python.org/3/library/string.html#format-string-syntax).
 
-For example, if the string to be replaced includes literal quotes,
-the search and replace patterns must include them too to match. Given the
-file `version.sh`:
+If the string to be replaced includes literal quotes, the search and replace patterns must include them to match. Given the file `version.sh`:
 
     MY_VERSION="1.2.3"
 
-Then the following search and replace patterns (including quotes) would be
-required:
+Then the following search and replace patterns (including quotes) would be required:
 
-```ini
-[bumpversion:file:version.sh]
-search = MY_VERSION="{current_version}"
-replace = MY_VERSION="{new_version}"
+```toml
+[[tool.bumpversion.files]]
+filename = "version.sh"
+search = "MY_VERSION=\"{current_version}\""
+replace = "MY_VERSION=\"{new_version}\""
 ```
 
 ---
 
-## Using bumpversion to maintain a go.mod file within a Go project
+## Using bumpversion to maintain a go mod file within a Go project
 
-In a module-aware Go project, when you create a major version of your module beyond v1, your module name will need to include the major version number (e.g. `github.com/myorg/myproject/v2`).
+In a module-aware Go project, when you create a major version of your module beyond v1, your module name will need to include the major version number (e.g., `github.com/myorg/myproject/v2`).
 
 You can use bump-my-version to maintain the major version number within the `go.mod` file by using the `parse` and `serialize` options, as in this example:
 
@@ -56,11 +50,11 @@ current_version = 2.0.0
 commit = True
 
 [[tool.bumpversion.files]]
-filename: go.mod
-parse = (?P<major>\d+)
-serialize = {major}
-search = module github.com/myorg/myproject/v{current_version}
-replace = module github.com/myorg/myproject/v{new_version}
+filename = "go.mod"
+parse = "(?P<major>\\d+)"
+serialize = "{major}"
+search = "module github.com/myorg/myproject/v{current_version}"
+replace = "module github.com/myorg/myproject/v{new_version}"
 ```
 
 - Example `go.mod` file:
@@ -86,5 +80,3 @@ Your `go.mod` file now contains this module directive:
 ```go
 module github.com/myorg/myproject/v3
 ```
-
-## 

docsrc/semantic-versioning-example.md

@@ -0,0 +1,44 @@
+# Semantic versioning example
+
+bumpversion flow:
+
+    1.0.0 => 1.0.1-dev1 => 1.0.1-dev2 = > 1.0.1-rc1 => 1.0.1-rc2 => 1.0.1
+             patch         build          release      build        release
+
+## Details
+
+Start with an initial release, say `1.0.0`.
+
+1. Create a new release, starting with a development build.
+
+        $ bumpversion patch
+        => 1.0.1-dev1
+
+2. Every time you build, bump `build`.
+
+        $ bumpversion build
+        => 1.0.1-dev2
+
+3. Go to release candidate by bumping `release`.
+
+        $ bumpversion release
+        => 1.0.1-rc1
+
+4. With every new build, bump `build`.
+
+        $ bumpversion build
+        => 1.0.1-rc2
+
+4. Finally, bump `release` to generate a final release for the current
+   `major` / `minor` / `patch` version.
+
+        $ bumpversion release
+        => 1.0.1
+
+
+## Notes
+
+*  Once the final release has been reached, it is not possible to bump
+   the `release` before bumping `patch` again. Trying to bump the release
+   while in final release state will issue
+   `ValueError: The part has already the maximum value among ['dev', 'rc', 'ga'] and cannot be bumped`.

docsrc/version-parts.md

@@ -1,112 +1,129 @@
 # Version parts
 
-A version string consists of one or more parts, e.g. the version `1.0.2` has three parts, separated by a dot (`.`) character. The names of these parts are defined in the named groups within the `parse` regular expression. The default configuration ( `(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)`) names them *major, minor,* and *patch.*
+- The version string is the rendering of some or all version parts.
+- While the version string may be rendered differently in various places, the value for all parts is maintained in bump-my-version's configuration.
+- The version parts are typically dependent on each other. Incrementing one part might change other elements.
+- You can compare two version strings (of the same project) and know which is more recent.
 
-By default all parts are considered numeric, that is their initial value is `0` and they are increased as integers. Also, the value `0` is considered to be
-optional if it's not needed for serialization, i.e. the version `1.4.0` is
-equal to `1.4` if `{major}.{minor}` is given as a `serialize` value.
+## Version configuration
 
-For advanced versioning schemes, non-numeric parts may be desirable (e.g. to
-identify [alpha or beta versions](http://en.wikipedia.org/wiki/Software_release_life_cycle#Stages_of_development)
-to indicate the stage of development, the flavor of the software package or
-a release name). To do so, you can use a `[bumpversion:part:…]` section
-containing the part's name (e.g. a part named `release_name` is configured in
-a section called `[bumpversion:part:release_name]`.
+A version configuration consists of the following:
 
-The following options are valid inside a part configuration:
+- A regular expression that will parse all the possible parts and name them
+- A list of one or more serialization formats
 
+A version string consists of one or more parts; e.g., version `1.0.2` has three parts, separated by a dot (`.`) character.
 
+The names of these parts are defined in the named groups within the `parse` regular expression. The default configuration calls them *major, minor,* and *patch.*
 
+The `serialize` configuration value is a list of default formats. You have the option for multiple serialization formats to omit *optional* values. For example, the following configuration:
 
+```toml
+serialize = [
+		"{major}.{minor}.{patch}",
+		"{major}.{minor}",
+]
+```
 
-Example:
+Bump-my-version will serialize using the first format if the `patch` value is not `0`. If the `patch` value *is* `0`, bump-my-version will use the second format.
 
-```ini
-[bumpversion:part:release_name]
-values =
-witty-warthog
-ridiculous-rat
-marvelous-mantis
-```
+## Version part configuration
 
----
+A version part configuration consists of the following:
 
-Example:
+- An incrementing function
+- An optional value
+- A first value
+- A flag indicating its dependence or independence of changes to other version parts
+
+### Incrementing functions
+
+There are two incrementing functions: numeric and value. The numeric function uses integer values and returns the next integer value. The values function uses a sequence of values and returns the next value until finished.
+
+By default, parts use the numeric function starting at 0.
 
-```ini
-[bumpversion]
-current_version = 1.alpha
-parse = (?P<num>\d+)(\.(?P<release>.*))?
-serialize =
-{num}.{release}
-{num}
-
-[bumpversion:part:release]
-optional_value = gamma
-values =
-alpha
-beta
-gamma
+You can configure a part using the values function by providing a list of values in the version part's configuration. For example, for the `release_name` part:
+
+```toml
+[tool.bumpversion.parts.release_name]
+values = [
+	"witty-warthog",
+	"ridiculous-rat",
+	"marvelous-mantis",
+]
 ```
 
-Here, `bump-my-version release` would bump `1.alpha` to `1.beta`. Executing
-`bump-my-version release` again would bump `1.beta` to `1`, because
-`release` being `gamma` is configured optional.
+### Optional values
+
+By default, the *first* value of a version part is considered *optional.* An optional value may be omitted from the version serialization. Using the example from above:
 
-You should consider the version of `1` to technically be `1.gamma`
-with the `.gamma` part not being serialized since it is optional.
-The `{num}` entry in the `serialize` list allows the release part to be
-hidden. If you only had `{num}.{release}`, an optional release will always
-be serialized.
+```toml
+serialize = [
+		"{major}.{minor}.{patch}",
+		"{major}.{minor}",
+]
+```
 
-Attempting to bump the release when it is the value of
-`gamma` will cause a `ValueError` as it will think you are trying to
-exceed the `values` list of the release part.
+Version `1.4.0` is rendered as `1.4` since the `patch` is `0`; as the first value, it is optional.
 
----
+Optional values are helpful for non-numeric version parts that indicate development stages, such as [alpha or beta](http://en.wikipedia.org/wiki/Software_release_life_cycle#Stages_of_development).
 
 Example:
 
-```ini
-[bumpversion]
-current_version = 1.alpha1
-parse = (?P<num>\d+)(\.(?P<release>.*)(?P<build>\d+))?
-serialize =
-{num}.{release}{build}
-
-[bumpversion:part:release]
-values =
-alpha
-beta
-gamma
-
-[bumpversion:part:build]
-first_value = 1
+```toml
+[tool.bumpversion]
+current_version = "1.0.0"
+parse = """(?x)
+    (?P<major>[0-9]+)
+    \\.(?P<minor>[0-9]+)
+    \\.(?P<patch>[0-9]+)
+    (?:
+        -(?P<pre_label>alpha|beta|stable)
+        (?:-(?P<pre_n>[0-9]+))?
+    )?
+"""
+serialize = [
+	"{major}.{minor}.{patch}-{pre_label}-{pre_n}",
+	"{major}.{minor}.{patch}",
+]
+
+[tool.bumpversion.parts.pre_label]
+optional_value = "stable"
+values =[
+	"alpha",
+	"beta",
+	"stable",
+]
 ```
 
-Here, `bump-my-version release` would bump `1.alpha1` to `1.beta1`.
+Bumping the `patch` part of version `1.0.0` would change the version to `1.0.1-alpha-0`. Bumping the `pre_label` part would change the version to `1.0.1-beta-0`. Bumping the `pre_label` part again would change the version to `1.0.1`. The `stable-0` is not serialized because both `stable` and `0` are *optional*.
 
-Without the `first_value = 1` of the build part configured,
-`bump-my-version release` would bump `1.alpha1` to `1.beta0`, starting
-the build at `0`.
+### First Values
 
+You can specify the starting number with the first_value configuration for numeric version parts.
 
+For example, if we added the following to the above configuration:
 
----
+```toml
+[tool.bumpversion.parts.pre_n]
+first_value = "1"
+```
 
-Example:
+Bumping the `patch` value of version `1.0.0` would change the version to `1.0.1-alpha-1` instead of `1.0.1-alpha-0`.
+
+### Independent Values
 
-```ini
-[bumpversion]
-current_version: 2.1.6-5123
-parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)\-(?P<build>\d+)
-serialize = {major}.{minor}.{patch}-{build}
+In the pattern `{major}.{minor}.{patch}-{pre_label}-{pre_n}`, each version part resets to its first value when the element preceding it changes. All these version parts are *dependent.*
 
-[bumpversion:file:VERSION.txt]
+You can include a value that incremented *independently* from the other parts, such as a `build` part: `{major}.{minor}.{patch}-{pre_label}-{pre_n}+{build}`—in the configuration for that part, set `independent=true`.
 
-[bumpversion:part:build]
-independent = True
+```toml
+[tool.bumpversion.parts.build]
+independent = true
 ```
 
-Here, `bump-my-version build` would bump `2.1.6-5123` to `2.1.6-5124`. Executing`bump-my-version major`
-would bump `2.1.6-5124` to `3.0.0-5124` without resetting the build number.
+## Reference
+
+- https://devopedia.org/semantic-versioning
+- https://semver.org
+- https://calver.org