Skip to content

Commit

Permalink
Merge pull request #144 from callowayproject/fix-docs
Browse files Browse the repository at this point in the history 
Fixed docs and cli help
  • Loading branch information
@coordt
coordt authored Feb 25, 2024
2 parents 8b93f81 + 8ac1087 commit e558fa1
Show file tree
Hide file tree
Showing 5 changed files with 343 additions and 395 deletions.
227 changes: 159 additions & 68 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,102 +44,193 @@ pip install --upgrade bump-my-version

Please find the changelog here: [CHANGELOG.md](CHANGELOG.md)

## Usage for version incrementing

There are two modes of operation: On the command line for single-file operation and using a configuration file (`pyproject.toml` or `.bumpversion.toml`) for more complex multi-file operations.

> **WARNING:**
>
> The invocation of `bump-my-version` changed in version 0.6.0. It split functionality into sub-commands. It remains backward-compatible with previous versions. Previous usage is discouraged and may be removed in a 1.0 release.
bump-my-version bump [options] [part] [file]

### `part`

_**required**_

The part of the version to increase, e.g. `minor`.

Valid values include the named groups defined in the `parse` configuration.

Example bumping 0.5.1 to 0.6.0:

bump-my-version bump --current-version 0.5.1 minor

### `file`

_**[optional]**_<br />
**default**: none

Additional files to modify.
## Semantic versioning example
<!--tutorial start-->

### Create a default configuration

The default configuration uses a simplified version of [semantic versioning](https://semver.org/).

```console title="Generating a default configuration"
$ bump-my-version sample-config --no-prompt --destination .bumpversion.toml
$ cat .bumpversion.toml
[tool.bumpversion]
current_version = "0.1.0"
parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
serialize = ["{major}.{minor}.{patch}"]
search = "{current_version}"
replace = "{new_version}"
regex = false
ignore_missing_version = false
tag = false
sign_tags = false
tag_name = "v{new_version}"
tag_message = "Bump version: {current_version} → {new_version}"
allow_dirty = false
commit = false
message = "Bump version: {current_version} → {new_version}"
commit_args = ""
```

These files are added to the list of files specified in your configuration file. If you want to rewrite only files specified on the command line, also use `--no-configured-files`.
### Visualize the versioning path

Example bumping 1.1.9 to 2.0.0:
You can see the potential versioning paths with the `show-bump` subcommand.

bump-my-version bump --current-version 1.1.9 major setup.py
```console title="Showing the potential versioning path"
$ bump-my-version show-bump
0.1.0 ── bump ─┬─ major ─ 1.0.0
├─ minor ─ 0.2.0
╰─ patch ─ 0.1.1
$ bump-my-version show-bump 1.2.3
1.2.3 ── bump ─┬─ major ─ 2.0.0
├─ minor ─ 1.3.0
╰─ patch ─ 1.2.4
```

## Configuration file
The default configuration only allows bumping the major, minor, or patch version. What if you wanted to support pre-release versions?

`bump-my-version` looks in four places for the configuration file to parse (in order of precedence):
### Add support for pre-release versions

1. `--config-file <FILE>` _(command line argument)_
2. `BUMPVERSION_CONFIG_FILE=file` _(environment variable)_
3. `.bumpversion.cfg` _(legacy)_
4. `.bumpversion.toml`
5. `setup.cfg` _(legacy)_
6. `pyproject.toml`
Alter the `parse` configuration to support pre-release versions. This `parse` option uses an extended (or verbose) regular expression to extract the version parts from the current version.

`.toml` files are recommended due to their type handling. We will likely drop support for `ini`-style formats in the future due to issues with formatting and parsing. You should add your configuration file to your source code management system.
```toml title="New parse configuration"
parse = """(?x)
(?P<major>0|[1-9]\\d*)\\.
(?P<minor>0|[1-9]\\d*)\\.
(?P<patch>0|[1-9]\\d*)
(?:
- # dash seperator for pre-release section
(?P<pre_l>[a-zA-Z-]+) # pre-release label
(?P<pre_n>0|[1-9]\\d*) # pre-release version number
)? # pre-release section is optional
"""
```

By using a configuration file, you no longer need to specify those options on the command line. The configuration file also allows greater flexibility in specifying how files are modified.
Alter the `serialize` configuration to support pre-release versions.

## Command-line Options
```toml title="New serialize configuration"
serialize = [
"{major}.{minor}.{patch}-{pre_l}{pre_n}",
"{major}.{minor}.{patch}",
]
```

Most of the configuration values above can also be given as an option on the command line.
Additionally, the following options are available:
Add a new configuration section for the `pre_l` part.

`--dry-run, -n`
Don't touch any files, just pretend. Best used with `--verbose`.
```toml title="New pre_l configuration"

`--no-configured-files`
Will not update/check files specified in the configuration file.
[tool.bumpversion.parts.pre_l]
values = ["dev", "rc", "final"]
optional_value = "final"
```

Similar to dry-run, but will also avoid checking the files. Also useful when you want to update just one file with e.g., `bump-my-version --no-configured-files major my-file.txt`
### Visualize the new versioning path

`--verbose, -v`
Print useful information to stderr. If specified more than once, it will output more information.
Now when you run `bump-my-version show-bump`, you can see the new pre-release versioning path.

`--list`
_DEPRECATED. Use `bump-my-version show` instead._ List machine-readable information to stdout for consumption by other programs.
```console title="Showing the new versioning path"
$ bump-my-version show-bump
0.1.0 ── bump ─┬─ major ─ 1.0.0-dev0
├─ minor ─ 0.2.0-dev0
├─ patch ─ 0.1.1-dev0
├─ pre_l ─ invalid: The part has already the maximum value among ['dev', 'rc', 'final'] and cannot be bumped.
╰─ pre_n ─ 0.1.0-final1
```

Example output:
The `pre_l` is not bump-able because it is already at the maximum value. The `pre_n` is bump-able because it is not at the maximum value.

current_version=0.0.18
new_version=0.0.19
If we run `bump-my-version show-bump 1.0.0-dev0`, we can see the new versioning path for a `dev` starting version.

`-h, --help`
Print help and exit
```console title="Showing the new versioning path for a dev version"
$ bump-my-version show-bump 1.0.0-dev0
1.0.0-dev0 ── bump ─┬─ major ─ 2.0.0-dev0
├─ minor ─ 1.1.0-dev0
├─ patch ─ 1.0.1-dev0
├─ pre_l ─ 1.0.0-rc0
╰─ pre_n ─ 1.0.0-dev1
```

## Using Bump My Version in a script
Finally, we can see the new versioning path for a `rc` starting version.

If you need to use the version generated by Bump My Version in a script, you can make use of the `show` subcommand.
```console title="Showing the new versioning path for an rc version"
$ bump-my-version show-bump 1.0.0-rc0
1.0.0-rc0 ── bump ─┬─ major ─ 2.0.0-dev0
├─ minor ─ 1.1.0-dev0
├─ patch ─ 1.0.1-dev0
├─ pre_l ─ 1.0.0
╰─ pre_n ─ 1.0.0-rc1
```

Say, for example, that you are using git-flow to manage your project and want to automatically create a release. When you issue `git flow release start` you need to know the new version before applying the change.
The full development and release path is:

The standard way to get it in a bash script is
- `1.0.0`
- `bump patch` → `1.0.1-dev0`
- `bump pre_n` → `1.0.1-dev1`
- `bump pre_l` → `1.0.1-rc0`
- `bump pre_n` → `1.0.1-rc1`
- `bump pre_l` → `1.0.1`

bump-my-version show new_version --increment <part>
1. You must decide on the next version before you start developing.
2. Development versions increase using `bump-my-version bump pre_n`.
3. Switch from development to release candidate using `bump-my-version bump pre_l`.
4. Release candidates increase using `bump-my-version bump pre_n`.
5. Switch from the release candidate to the final release using `bump-my-version bump pre_l`.

where `part` is the part of the version number you are updating.
### Automate the pre-release numbering

For example, if you are updating the minor number and looking for the new version number, this becomes:
The `pre_n` or pre-release number is a number that increases with each pre-release. You can automate this my changing the serialization configuration.

```console
$ bump-my-version show new_version --increment minor
1.1.0
```toml title="Serialize configuration with pre_n automation"
serialize = [
"{major}.{minor}.{patch}-{pre_l}{distance_to_latest_tag}",
"{major}.{minor}.{patch}",
]
```

The `distance_to_latest_tag` is a special value that is replaced with the number of commits since the last tag. This is a good value to use for the `pre_n` because it will always increase with each commit.

### Visualize the pre_n versioning path

Now when you run `bump-my-version show-bump`, you can see the new pre-release versioning path.

```console title="Showing the new versioning path with pre_n automation"

$ bump-my-version show-bump
0.1.0 ── bump ─┬─ major ─ 1.0.0-dev0
├─ minor ─ 0.2.0-dev0
├─ patch ─ 0.1.1-dev0
╰─ pre_l ─ invalid: The part has already the maximum value among ['dev', 'rc', 'final'] and cannot be bumped.
$ bump-my-version show-bump 1.0.0-dev0
1.0.0-dev0 ── bump ─┬─ major ─ 2.0.0-dev0
├─ minor ─ 1.1.0-dev0
├─ patch ─ 1.0.1-dev0
╰─ pre_l ─ 1.0.0-rc0
$ bump-my-version show-bump 1.0.0-rc0
1.0.0-rc0 ── bump ─┬─ major ─ 2.0.0-dev0
├─ minor ─ 1.1.0-dev0
├─ patch ─ 1.0.1-dev0
╰─ pre_l ─ 1.0.0
```

The `pre_n` path is now missing because it is automated.

The full development and release path now is:

- `1.0.0`
- `bump patch` → `1.0.1-dev0`
- each commit will increase → `1.0.1-dev1`
- `bump pre_l` → `1.0.1-rc0`
- each commit will increase → `1.0.1-rc1`
- `bump pre_l` → `1.0.1`

1. You must decide on the next version before you start developing.
2. Development versions increase automatically with each commit.
3. Switch from development to release candidate using `bump-my-version bump pre_l`.
4. Release candidate versions increase automatically with each commit.
5. Switch from the release candidate to the final release using `bump-my-version bump pre_l`.

<!--tutorial end-->

## Development & Contributing

Thank you, contributors! You can find a full list here: https://github.com/callowayproject/bump-my-version/graphs/contributors
Expand Down
3 changes: 2 additions & 1 deletion bumpversion/cli.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,8 @@ def cli(ctx: Context) -> None:
{
"name": "Committing and tagging",
"options": [
"--allow-dirty" "--commit",
"--allow-dirty",
"--commit",
"--commit-args",
"--message",
"--tag",
Expand Down
39 changes: 6 additions & 33 deletions docsrc/_static/css/field-list.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,60 +2,33 @@ dl.field-list .doc-param-default, dl.doc-field-list .doc-param-default {
float: none;
}

dd.doc-field-def > p:last-child {
padding-bottom: 0;
margin-bottom: 0;
}

dl.field-list, dl.doc-field-list {
.field-list > dl, dl.field-list, dl.doc-field-list {
display: flex;
flex-flow: row wrap;
padding-left: 10px;
}

dl.field-list > dt, dl.doc-field-list > dt {
.field-list > dl > dt, dl.field-list > dt, dl.doc-field-list > dt {
flex-basis: 20%;
font-weight: bold;
word-break: break-word;
padding: 10px 0;
border-bottom: 1px solid #e5e5e5;
}

dl.field-list > dt:after {
.field-list > dl > dt:after, dl.field-list > dt:after {
content: ":";
}

dl.field-list > dd.doc-field-def, dl.doc-field-list > dd.doc-field-def {
[dir=ltr] .field-list > dl > dd, dl.field-list > dd.doc-field-def, dl.doc-field-list > dd.doc-field-def {
flex-basis: 70%;
flex-grow: 1;
margin: 0;
padding: 10px 0 10px 10px;
border-bottom: 1px solid #e5e5e5;
}

dl {
margin-bottom: 15px;
}

dd > :first-child {
margin-top: 0;
}

dd ul, dd table {
margin-bottom: 10px;
}

dd {
margin-top: 3px;
margin-bottom: 10px;
margin-left: 30px;
}

dl > dd:last-child,
dl > dd:last-child > :last-child {
dd.doc-field-def > p:last-child {
padding-bottom: 0;
margin-bottom: 0;
}

dt:target, span.highlighted {
background-color: #fbe54e;
}
Loading

0 comments on commit e558fa1

Please sign in to comment.