Skip to content

Commit 6c3b4fe

Browse files
coordtcoordt
committed
Updated documentation
1 parent 1d9f84a commit 6c3b4fe

5 files changed

+170
-113
lines changed

‎docsrc/changelog.md

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
```{include} ../CHANGELOG.md
2+
```

‎docsrc/index.md

+2
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ caption: Contents
88
Introduction <readme>
99
usage
1010
configuration
11+
version-parts
12+
search-and-replace
1113
cli
1214
api
1315
contributing

‎docsrc/search-and-replace.md

+27-35
Original file line numberDiff line numberDiff line change
@@ -2,49 +2,43 @@
22

33
Given this `requirements.txt`:
44

5-
Django>=1.5.6,<1.6
6-
MyProject==1.5.6
5+
```text
6+
Django>=1.5.6,<1.6
7+
MyProject==1.5.6
8+
```
79

8-
using this `.bumpversion.cfg` will ensure only the line containing
9-
`MyProject` will be changed:
10+
using this `.bumpversion.toml` will ensure only the line containing `MyProject` will be changed:
1011

11-
```ini
12-
[bumpversion]
13-
current_version = 1.5.6
12+
```toml
13+
[tool.bumpversion]
14+
current_version = "1.5.6"
1415

15-
[bumpversion:file:requirements.txt]
16-
search = MyProject=={current_version}
17-
replace = MyProject=={new_version}
16+
[[tool.bumpversion:files]]
17+
filename = "requirements.txt"
18+
search = "MyProject=={current_version}"
19+
replace = "MyProject=={new_version}"
1820
```
1921

20-
Can be multiple lines, templated using [Python Format String Syntax](https://docs.python.org/3/library/string.html#format-string-syntax).
21-
22-
**NOTE**: (*Updated in v1.0.1*) It is important to point out that if a
23-
custom search pattern is configured, then `bump-my-version` will only perform
24-
a change if it finds an exact match and will not fallback to the default
25-
pattern. This is to prevent accidentally changing strings that match the
26-
default pattern when there is a typo in the custom search pattern.
22+
It can be multiple lines, templated using [Python Format String Syntax](https://docs.python.org/3/library/string.html#format-string-syntax).
2723

28-
For example, if the string to be replaced includes literal quotes,
29-
the search and replace patterns must include them too to match. Given the
30-
file `version.sh`:
24+
If the string to be replaced includes literal quotes, the search and replace patterns must include them to match. Given the file `version.sh`:
3125

3226
MY_VERSION="1.2.3"
3327

34-
Then the following search and replace patterns (including quotes) would be
35-
required:
28+
Then the following search and replace patterns (including quotes) would be required:
3629

37-
```ini
38-
[bumpversion:file:version.sh]
39-
search = MY_VERSION="{current_version}"
40-
replace = MY_VERSION="{new_version}"
30+
```toml
31+
[[tool.bumpversion.files]]
32+
filename = "version.sh"
33+
search = "MY_VERSION=\"{current_version}\""
34+
replace = "MY_VERSION=\"{new_version}\""
4135
```
4236

4337
---
4438

45-
## Using bumpversion to maintain a go.mod file within a Go project
39+
## Using bumpversion to maintain a go mod file within a Go project
4640

47-
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`).
41+
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`).
4842

4943
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:
5044

@@ -56,11 +50,11 @@ current_version = 2.0.0
5650
commit = True
5751

5852
[[tool.bumpversion.files]]
59-
filename: go.mod
60-
parse = (?P<major>\d+)
61-
serialize = {major}
62-
search = module github.com/myorg/myproject/v{current_version}
63-
replace = module github.com/myorg/myproject/v{new_version}
53+
filename = "go.mod"
54+
parse = "(?P<major>\\d+)"
55+
serialize = "{major}"
56+
search = "module github.com/myorg/myproject/v{current_version}"
57+
replace = "module github.com/myorg/myproject/v{new_version}"
6458
```
6559

6660
- Example `go.mod` file:
@@ -86,5 +80,3 @@ Your `go.mod` file now contains this module directive:
8680
```go
8781
module github.com/myorg/myproject/v3
8882
```
89-
90-
##

‎docsrc/semantic-versioning-example.md

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Semantic versioning example
2+
3+
bumpversion flow:
4+
5+
1.0.0 => 1.0.1-dev1 => 1.0.1-dev2 = > 1.0.1-rc1 => 1.0.1-rc2 => 1.0.1
6+
patch build release build release
7+
8+
## Details
9+
10+
Start with an initial release, say `1.0.0`.
11+
12+
1. Create a new release, starting with a development build.
13+
14+
$ bumpversion patch
15+
=> 1.0.1-dev1
16+
17+
2. Every time you build, bump `build`.
18+
19+
$ bumpversion build
20+
=> 1.0.1-dev2
21+
22+
3. Go to release candidate by bumping `release`.
23+
24+
$ bumpversion release
25+
=> 1.0.1-rc1
26+
27+
4. With every new build, bump `build`.
28+
29+
$ bumpversion build
30+
=> 1.0.1-rc2
31+
32+
4. Finally, bump `release` to generate a final release for the current
33+
`major` / `minor` / `patch` version.
34+
35+
$ bumpversion release
36+
=> 1.0.1
37+
38+
39+
## Notes
40+
41+
* Once the final release has been reached, it is not possible to bump
42+
the `release` before bumping `patch` again. Trying to bump the release
43+
while in final release state will issue
44+
`ValueError: The part has already the maximum value among ['dev', 'rc', 'ga'] and cannot be bumped`.

‎docsrc/version-parts.md

+95-78
Original file line numberDiff line numberDiff line change
@@ -1,112 +1,129 @@
11
# Version parts
22

3-
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.*
3+
- The version string is the rendering of some or all version parts.
4+
- While the version string may be rendered differently in various places, the value for all parts is maintained in bump-my-version's configuration.
5+
- The version parts are typically dependent on each other. Incrementing one part might change other elements.
6+
- You can compare two version strings (of the same project) and know which is more recent.
47

5-
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
6-
optional if it's not needed for serialization, i.e. the version `1.4.0` is
7-
equal to `1.4` if `{major}.{minor}` is given as a `serialize` value.
8+
## Version configuration
89

9-
For advanced versioning schemes, non-numeric parts may be desirable (e.g. to
10-
identify [alpha or beta versions](http://en.wikipedia.org/wiki/Software_release_life_cycle#Stages_of_development)
11-
to indicate the stage of development, the flavor of the software package or
12-
a release name). To do so, you can use a `[bumpversion:part:…]` section
13-
containing the part's name (e.g. a part named `release_name` is configured in
14-
a section called `[bumpversion:part:release_name]`.
10+
A version configuration consists of the following:
1511

16-
The following options are valid inside a part configuration:
12+
- A regular expression that will parse all the possible parts and name them
13+
- A list of one or more serialization formats
1714

15+
A version string consists of one or more parts; e.g., version `1.0.2` has three parts, separated by a dot (`.`) character.
1816

17+
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.*
1918

19+
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:
2020

21+
```toml
22+
serialize = [
23+
"{major}.{minor}.{patch}",
24+
"{major}.{minor}",
25+
]
26+
```
2127

22-
Example:
28+
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.
2329

24-
```ini
25-
[bumpversion:part:release_name]
26-
values =
27-
witty-warthog
28-
ridiculous-rat
29-
marvelous-mantis
30-
```
30+
## Version part configuration
3131

32-
---
32+
A version part configuration consists of the following:
3333

34-
Example:
34+
- An incrementing function
35+
- An optional value
36+
- A first value
37+
- A flag indicating its dependence or independence of changes to other version parts
38+
39+
### Incrementing functions
40+
41+
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.
42+
43+
By default, parts use the numeric function starting at 0.
3544

36-
```ini
37-
[bumpversion]
38-
current_version = 1.alpha
39-
parse = (?P<num>\d+)(\.(?P<release>.*))?
40-
serialize =
41-
{num}.{release}
42-
{num}
43-
44-
[bumpversion:part:release]
45-
optional_value = gamma
46-
values =
47-
alpha
48-
beta
49-
gamma
45+
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:
46+
47+
```toml
48+
[tool.bumpversion.parts.release_name]
49+
values = [
50+
"witty-warthog",
51+
"ridiculous-rat",
52+
"marvelous-mantis",
53+
]
5054
```
5155

52-
Here, `bump-my-version release` would bump `1.alpha` to `1.beta`. Executing
53-
`bump-my-version release` again would bump `1.beta` to `1`, because
54-
`release` being `gamma` is configured optional.
56+
### Optional values
57+
58+
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:
5559

56-
You should consider the version of `1` to technically be `1.gamma`
57-
with the `.gamma` part not being serialized since it is optional.
58-
The `{num}` entry in the `serialize` list allows the release part to be
59-
hidden. If you only had `{num}.{release}`, an optional release will always
60-
be serialized.
60+
```toml
61+
serialize = [
62+
"{major}.{minor}.{patch}",
63+
"{major}.{minor}",
64+
]
65+
```
6166

62-
Attempting to bump the release when it is the value of
63-
`gamma` will cause a `ValueError` as it will think you are trying to
64-
exceed the `values` list of the release part.
67+
Version `1.4.0` is rendered as `1.4` since the `patch` is `0`; as the first value, it is optional.
6568

66-
---
69+
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).
6770

6871
Example:
6972

70-
```ini
71-
[bumpversion]
72-
current_version = 1.alpha1
73-
parse = (?P<num>\d+)(\.(?P<release>.*)(?P<build>\d+))?
74-
serialize =
75-
{num}.{release}{build}
76-
77-
[bumpversion:part:release]
78-
values =
79-
alpha
80-
beta
81-
gamma
82-
83-
[bumpversion:part:build]
84-
first_value = 1
73+
```toml
74+
[tool.bumpversion]
75+
current_version = "1.0.0"
76+
parse = """(?x)
77+
(?P<major>[0-9]+)
78+
\\.(?P<minor>[0-9]+)
79+
\\.(?P<patch>[0-9]+)
80+
(?:
81+
-(?P<pre_label>alpha|beta|stable)
82+
(?:-(?P<pre_n>[0-9]+))?
83+
)?
84+
"""
85+
serialize = [
86+
"{major}.{minor}.{patch}-{pre_label}-{pre_n}",
87+
"{major}.{minor}.{patch}",
88+
]
89+
90+
[tool.bumpversion.parts.pre_label]
91+
optional_value = "stable"
92+
values =[
93+
"alpha",
94+
"beta",
95+
"stable",
96+
]
8597
```
8698

87-
Here, `bump-my-version release` would bump `1.alpha1` to `1.beta1`.
99+
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*.
88100

89-
Without the `first_value = 1` of the build part configured,
90-
`bump-my-version release` would bump `1.alpha1` to `1.beta0`, starting
91-
the build at `0`.
101+
### First Values
92102

103+
You can specify the starting number with the first_value configuration for numeric version parts.
93104

105+
For example, if we added the following to the above configuration:
94106

95-
---
107+
```toml
108+
[tool.bumpversion.parts.pre_n]
109+
first_value = "1"
110+
```
96111

97-
Example:
112+
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`.
113+
114+
### Independent Values
98115

99-
```ini
100-
[bumpversion]
101-
current_version: 2.1.6-5123
102-
parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)\-(?P<build>\d+)
103-
serialize = {major}.{minor}.{patch}-{build}
116+
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.*
104117

105-
[bumpversion:file:VERSION.txt]
118+
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`.
106119

107-
[bumpversion:part:build]
108-
independent = True
120+
```toml
121+
[tool.bumpversion.parts.build]
122+
independent = true
109123
```
110124

111-
Here, `bump-my-version build` would bump `2.1.6-5123` to `2.1.6-5124`. Executing`bump-my-version major`
112-
would bump `2.1.6-5124` to `3.0.0-5124` without resetting the build number.
125+
## Reference
126+
127+
- https://devopedia.org/semantic-versioning
128+
- https://semver.org
129+
- https://calver.org

0 commit comments

Comments
 (0)