Skip to content

Commit

Permalink
fixup! feat: Support PEP440 versioning scheme
Browse files Browse the repository at this point in the history
  • Loading branch information
dummy committed Mar 27, 2024
1 parent 16ba83e commit 226ed86
Show file tree
Hide file tree
Showing 11 changed files with 1,057 additions and 178 deletions.
10 changes: 5 additions & 5 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.

### Bug Fixes

- Assign commits to versions following their commit graph (follow semver) ([f191ed7](https://github.com/pawamoy/git-changelog/commit/f191ed7c05029674e52c8ada55e0d9e861c320cc) by Christian Meffert). [Issue-70](https://github.com/pawamoy/git-changelog/issues/70), [Issue-42](https://github.com/pawamoy/git-changelog/issues/42), [PR-72](https://github.com/pawamoy/git-changelog/pull/72), Co-authored-by: Timothée Mazzucotelli <[email protected]>
- Assign commits to versions following their commit graph (follow SemVer) ([f191ed7](https://github.com/pawamoy/git-changelog/commit/f191ed7c05029674e52c8ada55e0d9e861c320cc) by Christian Meffert). [Issue-70](https://github.com/pawamoy/git-changelog/issues/70), [Issue-42](https://github.com/pawamoy/git-changelog/issues/42), [PR-72](https://github.com/pawamoy/git-changelog/pull/72), Co-authored-by: Timothée Mazzucotelli <[email protected]>
- Ignore bump on new Git repo without unreleased commits ([438968c](https://github.com/pawamoy/git-changelog/commit/438968c711da86bc7398246deb8679e534d67453) by Christian Meffert). [PR-71](https://github.com/pawamoy/git-changelog/pull/71)
- Use provided version when creating first changelog entry ([dd264cc](https://github.com/pawamoy/git-changelog/commit/dd264cc9f8c530371b33c1e5d3b5083839659bd9) by Christian Meffert). [PR-69](https://github.com/pawamoy/git-changelog/pull/69)

Expand All @@ -22,7 +22,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.

### Features

- Add option to enable/disable "zerover" behavior ([7d0c259](https://github.com/pawamoy/git-changelog/commit/7d0c259f2ec4c5666d15a3616de8765f52fb282c) by Mark Minakov). [Issue #57](https://github.com/pawamoy/git-changelog/issues/57), [PR #58](https://github.com/pawamoy/git-changelog/pull/58), Co-authored-by: Timothée Mazzucotelli <[email protected]>
- Add option to enable/disable "ZeroVer" behavior ([7d0c259](https://github.com/pawamoy/git-changelog/commit/7d0c259f2ec4c5666d15a3616de8765f52fb282c) by Mark Minakov). [Issue #57](https://github.com/pawamoy/git-changelog/issues/57), [PR #58](https://github.com/pawamoy/git-changelog/pull/58), Co-authored-by: Timothée Mazzucotelli <[email protected]>
- Add `-F,--filter-commits` to filter by revision-range ([e016965](https://github.com/pawamoy/git-changelog/commit/e0169654c917497ce88966fca1baf47d0a4586f7) by Pedro Brochado). [Issue #63](https://github.com/pawamoy/git-changelog/issues/63), [Issue #16](https://github.com/pawamoy/git-changelog/issues/16), [PR #64](https://github.com/pawamoy/git-changelog/pull/64), Co-authored-by: Timothée Mazzucotelli <[email protected]>

### Bug Fixes
Expand Down Expand Up @@ -150,7 +150,7 @@ Lots of new features! Usage is documented here: https://pawamoy.github.io/git-ch
- Clean up body to fix parsing trailers ([1183c25](https://github.com/pawamoy/git-changelog/commit/1183c259c9b16eea2043a930f7ff775e058c9733) by Timothée Mazzucotelli).
- Fix building commit body ([f76bf32](https://github.com/pawamoy/git-changelog/commit/f76bf3205ab4e696ec9907e95517817e6c04af70) by Timothée Mazzucotelli).
- Fix spacing in keepachangelog templates ([cf5117a](https://github.com/pawamoy/git-changelog/commit/cf5117a27fc28503a12bc133c5ed663628b02740) by Timothée Mazzucotelli).
- Don't crash when trying to parse the latest tag as semver ([e90aa2b](https://github.com/pawamoy/git-changelog/commit/e90aa2be1c94fa792f26b82e0db86b10924a8c83) by Timothée Mazzucotelli).
- Don't crash when trying to parse the latest tag as SemVer ([e90aa2b](https://github.com/pawamoy/git-changelog/commit/e90aa2be1c94fa792f26b82e0db86b10924a8c83) by Timothée Mazzucotelli).
- Keep a Changelog template: don't capitalize commit summary ([87348ed](https://github.com/pawamoy/git-changelog/commit/87348ed1503b043d6bfae2e113c09f7c9c166501) by Timothée Mazzucotelli).
- Keep a Changelog template: respect sections order (don't sort) ([f645e62](https://github.com/pawamoy/git-changelog/commit/f645e62bf49ed61601ba095715f9098b6935ad2f) by Timothée Mazzucotelli).
- Use `importlib.metadata` instead of `pkg_resources` to get current version ([79109d0](https://github.com/pawamoy/git-changelog/commit/79109d0f4e55f821bb8c8299477c7d0693435445) by Timothée Mazzucotelli).
Expand Down Expand Up @@ -191,12 +191,12 @@ Lots of new features! Usage is documented here: https://pawamoy.github.io/git-ch

### Bug Fixes

- Properly bump semver version ([ecc7dd4](https://github.com/pawamoy/git-changelog/commit/ecc7dd430719c90b289acf7f29adb0b82e193fa8) by Kevin Squire). References: [#31](https://github.com/pawamoy/git-changelog/issues/31)
- Properly bump SemVer version ([ecc7dd4](https://github.com/pawamoy/git-changelog/commit/ecc7dd430719c90b289acf7f29adb0b82e193fa8) by Kevin Squire). References: [#31](https://github.com/pawamoy/git-changelog/issues/31)
- Fix typo in keepachangelog template ([fa9b434](https://github.com/pawamoy/git-changelog/commit/fa9b4349c1a954a3029e5b35ac306a22fc08babe) by Alexander Schleifer). [PR #28](https://github.com/pawamoy/git-changelog/pull/28)

### Code Refactoring

- Use semver to bump version more reliably ([b68a565](https://github.com/pawamoy/git-changelog/commit/b68a565fce51f8d0e94f0f67c98dea30e421dd8f) by Timothée Mazzucotelli).
- Use SemVer to bump version more reliably ([b68a565](https://github.com/pawamoy/git-changelog/commit/b68a565fce51f8d0e94f0f67c98dea30e421dd8f) by Timothée Mazzucotelli).

## [0.4.2](https://github.com/pawamoy/git-changelog/releases/tag/0.4.2) - 2021-01-06

Expand Down
3 changes: 2 additions & 1 deletion docs/cli.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,8 @@ option_to_docs = {
"sections": "#choose-the-sections-to-render",
"template": "#choose-a-changelog-template",
"version_regex": "#update-changelog-in-place",
"zerover": "#understand-the-relationship-with-semver",
"versioning": "#choose-a-versioning-scheme",
"zerover": "#zerover",
}


Expand Down
219 changes: 198 additions & 21 deletions docs/usage.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,15 +36,15 @@ to guess the new version by bumping the latest version
based on the semantics of your commits:

```bash
git-changelog -bio CHANGELOG.md -c angular
git-changelog -Bauto -io CHANGELOG.md -c angular
```

Same thing, but also parse Git trailers
and choose the sections to render, and their order
(author's favorite!):

```bash
git-changelog -Tbio CHANGELOG.md -c angular -s build,deps,fix,feat,refactor
git-changelog -B auto -Tio CHANGELOG.md -c angular -s build,deps,fix,feat,refactor
```

Generate a changelog using a custom template,
Expand Down Expand Up @@ -74,6 +74,7 @@ build_and_render(
parse_trailers=True,
parse_refs=False,
sections=("build", "deps", "feat", "fix", "refactor"),
versioning="pep440",
bump="auto",
in_place=True,
)
Expand Down Expand Up @@ -124,11 +125,12 @@ marker-line = "<!-- insertion marker -->"
output = "output.log"
parse-refs = false
parse-trailers = false
provider = "gitlab"
repository = "."
sections = ["fix", "maint"]
template = "angular"
version-regex = "^## \\\\[(?P<version>v?[^\\\\]]+)"
provider = "gitlab"
versioning = "semver"
zerover = true
```

Expand All @@ -140,14 +142,18 @@ settings must be found in the appropriate section:
bump = "minor"
convention = "conventional"
in-place = false
filter-commits = "0.5.0.."
marker-line = "<!-- insertion marker -->"
output = "output.log"
parse-refs = false
parse-trailers = false
provider = "gitlab"
repository = "."
sections = "fix,maint"
template = "keepachangelog"
version-regex = "^## \\\\[(?P<version>v?[^\\\\]]+)"
versioning = "semver"
zerover = true
```

## Output a changelog
Expand Down Expand Up @@ -395,7 +401,7 @@ footer = "Copyright 2024 My Company"
[(--filter-commits)](cli.md#filter_commits)

Sometimes it may be useful to use a limited set of commits, for example, if your
project has migrated to semver recently and you want to ignore old non-conventional commits.
project has migrated to SemVer recently and you want to ignore old non-conventional commits.

This is possible through the option `-F`, `--filter-commits`, which takes a
*revision-range* to select the commits that will be used in the changelog.
Expand All @@ -418,9 +424,13 @@ git-changelog --filter-commits "2c0dbb8.."
## Understand the relationship with SemVer

[(--bump)](cli.md#bump)<br>
[(--versioning)](cli.md#versioning)<br>
[(--zerover)](cli.md#zerover)

[Semver][semver], or Semantic Versioning, helps users of tools and libraries
*Although git-changelog supports several [versioning schemes](#choose-a-versioning-scheme),
SemVer plays a particular role when managing versions.*

[SemVer][semver], or Semantic Versioning, helps users of tools and libraries
understand the impact of version changes. To quote SemVer itself:

> Given a version number MAJOR.MINOR.PATCH, increment the:
Expand Down Expand Up @@ -449,30 +459,42 @@ You can also specify a version to bump to directly:
git-changelog --bump 2.3.1
```

Or which part of the version to bump, resetting
numbers on its right to 0:
As different schemes have different bumping strategies,
the selected scheme will affect the `--bump` option.
See [PEP 440 strategies](#pep-440) and [SemVer strategies](#semver).

```bash
git-changelog --bump major # 1.2.3 -> 2.0.0
git-changelog --bump minor # 1.2.3 -> 1.3.0
git-changelog --bump patch # 1.2.3 -> 1.2.4
```
### ZeroVer

Note that by default, "ZeroVer" mode is activated,
which means that a breaking change will only bump the major version
if the major version is already at `1` or more,
otherwise it will bump the minor version.

While this behavior is described in SemVer's specification,
the "ZeroVer" name comes from the satyrical
[ZeroVer (or zer0ver, 0ver) versioning scheme](https://0ver.org/).

Note that, by default the major number won't be bumped if the latest version is 0.x.
Instead, the minor number will be bumped:
When you are ready to bump to 1.0.0,
just pass this version as value, or use the `-Z`, `--no-zerover` flag.

Let say we are at version `0.1.0`, and unreleased commits
contain breaking changes:

```bash
git-changelog --bump major # 0.1.2 -> 0.2.0, same as minor because 0.x
git-changelog --bump minor # 0.1.2 -> 0.2.0
git-changelog --bump auto # 0.2.0
git-changelog --bump auto -Z # 1.0.0
git-changelog --bump major # 0.2.0
git-changelog --bump major -Z # 1.0.0
```

In that case, when you are ready to bump to 1.0.0,
just pass this version as value, or use the `-Z`, `--no-zerover` flag:
If we are already at version `1.0.0`, and unreleased commits
contain breaking changes again:

```bash
git-changelog --bump 1.0.0
git-changelog --bump auto --no-zerover
git-changelog --bump major --no-zerover
git-changelog --bump auto # 2.0.0
git-changelog --bump auto -Z # 2.0.0, same
git-changelog --bump major # 2.0.0
git-changelog --bump major -Z # 2.0.0, same
```

If you use *git-changelog* in CI, to update your changelog automatically,
Expand All @@ -483,6 +505,154 @@ to bump to v1, set `zerover = false` and commit it as a breaking change.
Once v1 is released, the setting has no use anymore, and you can remove it
from your configuration file.

## Choose a versioning scheme

[(--bump)](cli.md#bump)<br>
[(--versioning)](cli.md#versioning)<br>
[(--zerover)](cli.md#zerover)

*git-changelog* currently supports the following versioning schemes:

- `pep440`, see [PEP 440][pep440]
- `semver`, see [SemVer][semver]

Versioning schemes are useful to *git-changelog* when grouping commits
from your Git history into versions, and when bumping versions.

To choose a specific scheme, use the `-n`, `--versioning` CLI option:

```bash
git-changelog -n pep440
```

By default, and for history and backward compatibility reasons,
it uses the SemVer scheme by default.

As different schemes have different bumping strategies,
the selected scheme will affect the `--bump` option.

### PEP 440

The bumping strategies supported by the PEP 440 scheme
are described in the table below.
Bumping a specific part of the version will remove or reset the parts
on its right to 0.

Strategy | Example | Description
--------------------- | --------------------- | -----------
`auto` | - | Guess which of major, minor or micro to bump<br>thanks to the Git history and commit message conventions.
`epoch` | `1!1` → `2!1` | Bump [epoch][pep440-epoch], keeping [final release][pep440-release] only.
`release` | `1rc2` → `1` | Bump version to a [final release][pep440-release].
`major` | `1.1` → `2.0` | Bump major version.
`minor` | `1.1.1` → `1.2.0` | Bump minor version.
`micro` (or `patch`) | `1.1.1.1` → `1.1.2.0` | Bump micro version.
`pre` | `1a0` → `1a1` | Bump current [pre-release][pep440-pre] (alpha `a`, beta `b` or release candidate `rc`).
`alpha` | `1a0` → `1a1` | Bump current alpha pre-release.
`beta` | `1b0` → `1b1` | Bump current beta pre-release.
`candidate` | `1rc0` → `1rc1` | Bump current candidate pre-release.
`post` | `1.post0` → `1.post1` | Bump to a [post-release][pep440-post].
`dev` | `1.dev0` → `1.dev1` | Bump current [dev-release][pep440-dev].
`auto+alpha` | - | Guess major/minor/micro bump, and set it to alpha pre-release.
`auto+beta` | - | Guess major/minor/micro bump, and set it to beta pre-release.
`auto+candidate` | - | Guess major/minor/micro bump, and set it to candidate pre-release.
`auto+dev` | - | Guess major/minor/micro bump, and set it to dev-release.
`auto+alpha+dev` | - | Guess major/minor/micro bump, and set it to alpha pre-release and dev-release.
`auto+beta+dev` | - | Guess major/minor/micro bump, and set it to beta pre-release and dev-release.
`auto+candidate+dev` | - | Guess major/minor/micro bump, and set it to candidate pre-release and dev-release.
`major+alpha` | `1` → `2a0` | Bump major version and set it to alpha pre-release.
`major+beta` | `1` → `2b0` | Bump major version and set it to beta pre-release.
`major+candidate` | `1` → `2rc0` | Bump major version and set it to candidate pre-release.
`major+dev` | `1` → `2.dev0` | Bump major version and set it to dev-release.
`major+alpha+dev` | `1` → `2a0.dev0` | Bump major version and set it to alpha pre-release and dev-release.
`major+beta+dev` | `1` → `2b0.dev0` | Bump major version and set it to beta pre-release and dev-release.
`major+candidate+dev` | `1` → `2rc0.dev0` | Bump major version and set it to candidate pre-release and dev-release.
`minor+alpha` | `1` → `1.1a0` | Bump minor version and set it to alpha pre-release.
`minor+beta` | `1` → `1.1b0` | Bump minor version and set it to beta pre-release.
`minor+candidate` | `1` → `1.1rc0` | Bump minor version and set it to candidate pre-release.
`minor+dev` | `1` → `1.1.dev0` | Bump minor version and set it to dev-release.
`minor+alpha+dev` | `1` → `1.1a0.dev0` | Bump minor version and set it to alpha pre-release and dev-release.
`minor+beta+dev` | `1` → `1.1b0.dev0` | Bump minor version and set it to beta pre-release and dev-release.
`minor+candidate+dev` | `1` → `1.1rc0.dev0` | Bump minor version and set it to candidate pre-release and dev-release.
`micro+alpha` | `1` → `1.0.1a0` | Bump micro version and set it to alpha pre-release.
`micro+beta` | `1` → `1.0.1b0` | Bump micro version and set it to beta pre-release.
`micro+candidate` | `1` → `1.0.1rc0` | Bump micro version and set it to candidate pre-release.
`micro+dev` | `1` → `1.0.1.dev0` | Bump micro version and set it to dev-release.
`micro+alpha+dev` | `1` → `1.0.1a0.dev0` | Bump micro version and set it to alpha pre-release and dev-release.
`micro+beta+dev` | `1` → `1.0.1b0.dev0` | Bump micro version and set it to beta pre-release and dev-release.
`micro+candidate+dev` | `1` → `1.0.1rc0.dev0` | Bump micro version and set it to candidate pre-release and dev-release.
`alpha+dev` | `1a0` → `1a1.dev0` | Bump current alpha pre-release and set it to a dev-release.
`beta+dev` | `1b0` → `1b1.dev0` | Bump current beta pre-release and set it to a dev-release.
`candidate+dev` | `1rc0` → `1rc1.dev0` | Bump current candidate pre-release and set it to a dev-release.

Try it out:

```pyodide install="git-changelog"
from git_changelog.versioning import bump_pep440
# "auto" strategies are not directly supported by this function
print(bump_pep440("1.2.3", "minor+alpha"))
```

The `v` prefix will be preserved when bumping a version: `v1` -> `v2`.

The bumping strategies for PEP 440 try to make the most sense,
allowing you to bump in a semantic way and preventing version downgrade mistakes.
Specifically, it is not possible:

- to bump from a final release version to a pre-release or a dev-release version
- to bump from a pre-release version to a lower pre-release version or a dev-version
- more generally, to bump from any version to any lower version

If you need to "bump" to a version that is lower than the latest released one,
you must explicitely pass the version to the `--bump` option:

```bash
# latest release is 1.1
git-changelog --bump 1.0
```

### SemVer

The bumping strategies supported by the SemVer scheme
are described in the table below.
Bumping a specific part of the version will remove or reset the parts
on its right to 0.

Strategy | Example | Description
--------------------- | --------------------- | -----------
`auto` | - | Guess which of major, minor or patch to bump<br>thanks to the Git history and commit message conventions.
`major` | `1.1.1` → `2.0.0` | Bump major version.
`minor` | `1.1.1` → `1.2.0` | Bump minor version.
`patch` | `1.1.1` → `1.1.2` | Bump micro version.
`release` | `1.1.1-a2` → `1.1.1` | Bump version to a final release (remove pre-release and build metadata).

Try it out:

```pyodide install="git-changelog"
from git_changelog.versioning import bump_semver
# the "auto" strategy is not directly supported by this function
print(bump_semver("1.2.3", "minor"))
```

The `v` prefix will be preserved when bumping a version: `v1.0.0` -> `v2.0.0`.

The bumping strategies for SemVer will prevent you from bumping from any version to a lower one.
It does not support bump pre-release metadata or build metadata
because these are not standardized.

If you need to "bump" to a version that is lower than the latest released one,
or to add pre-release or build metadata,
you must explicitely pass the version to the `--bump` option:

```bash
# downgrade
git-changelog --bump 1.1.0

# add pre-release metadata
git-changelog --bump 2.0.0-alpha1
```

## Parse additional information in commit messages

*git-changelog* is able to parse the body of commit messages
Expand Down Expand Up @@ -687,3 +857,10 @@ and `--marker-line`.
[keepachangelog-template]: https://github.com/pawamoy/git-changelog/tree/main/src/git_changelog/templates/keepachangelog.md
[builtin-templates]: https://github.com/pawamoy/git-changelog/tree/main/src/git_changelog/templates
[control-whitespace]: https://jinja.palletsprojects.com/en/3.1.x/templates/#whitespace-control
[pep440]: https://peps.python.org/pep-0440/
[pep440-epoch]: https://peps.python.org/pep-0440/#version-epochs
[pep440-pre]: https://peps.python.org/pep-0440/#pre-releases
[pep440-post]: https://peps.python.org/pep-0440/#post-releases
[pep440-dev]: https://peps.python.org/pep-0440/#developmental-releases
[pep440-release]: https://peps.python.org/pep-0440/#final-releases
[pep440-local]: https://peps.python.org/pep-0440/#local-version-identifiers
Loading

0 comments on commit 226ed86

Please sign in to comment.