Skip to content

Commit 21db1d1

Browse files
fleetingbytesfleetingbytes
authored
Develop (#28)
fixes #27
1 parent 443f867 commit 21db1d1

File tree

12 files changed

+468
-3
lines changed

12 files changed

+468
-3
lines changed

‎CHANGELOG.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,14 @@
22

33
<!-- towncrier release notes start -->
44

5+
## [0.2.1](https://github.com/Nagidal/hatch-semver/tree/0.2.1) - 2022-11-15
6+
7+
8+
### Documentation
9+
10+
- Moved user-docs to docs [#27](https://github.com/Nagidal/hatch-semver/issues/27)
11+
12+
513
## [0.2.0](https://github.com/Nagidal/hatch-semver/tree/0.2.0) - 2022-11-15
614

715

‎docs/CHANGELOG.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Changelog
2+
3+
<!-- towncrier release notes start -->
4+
5+
## [0.2.1](https://github.com/Nagidal/hatch-semver/tree/0.2.1) - 2022-11-15
6+
7+
8+
### Documentation
9+
10+
- Moved user-docs to docs [#27](https://github.com/Nagidal/hatch-semver/issues/27)
11+
12+
13+
## [0.2.0](https://github.com/Nagidal/hatch-semver/tree/0.2.0) - 2022-11-15
14+
15+
16+
### Documentation
17+
18+
- Wrote user and api documentation [#25](https://github.com/Nagidal/hatch-semver/issues/25)
19+
20+
21+
## [0.1.0](https://github.com/Nagidal/hatch-semver/tree/0.1.0) - 2022-11-13
22+
23+
24+
### New Features
25+
26+
- Added inline options for prerelease and build tokens [#23](https://github.com/Nagidal/hatch-semver/issues/23)
27+
28+
29+
### Bugfixes
30+
31+
- Fixed undefined ValeError [#16](https://github.com/Nagidal/hatch-semver/issues/16)
32+
- Can bump prereleases now [#17](https://github.com/Nagidal/hatch-semver/issues/17)
33+
- Can bump builds now [#18](https://github.com/Nagidal/hatch-semver/issues/18)
34+
- Can update version to release [#22](https://github.com/Nagidal/hatch-semver/issues/22)
35+
36+
37+
### Development Details
38+
39+
- Created tests [#19](https://github.com/Nagidal/hatch-semver/issues/19)
40+
41+
42+
## [0.0.8](https://github.com/Nagidal/hatch-semver/tree/0.0.8) - 2022-11-10
43+
44+
45+
### Bugfixes
46+
47+
- Fixed another ValueError when bumping major version [#14](https://github.com/Nagidal/hatch-semver/issues/14)
48+
49+
50+
## [0.0.7](https://github.com/Nagidal/hatch-semver/tree/0.0.7) - 2022-11-10
51+
52+
53+
### Bugfixes
54+
55+
- Fixed NameError when bumping version [#12](https://github.com/Nagidal/hatch-semver/issues/12)
56+
57+
58+
## [0.0.6](https://github.com/Nagidal/hatch-semver/tree/0.0.6) - 2022-11-10
59+
60+
61+
### Bugfixes
62+
63+
- Major version should be bumpable now [#10](https://github.com/Nagidal/hatch-semver/issues/10)
64+
65+
66+
## [0.0.5](https://github.com/Nagidal/hatch-semver/tree/0.0.5) - 2022-11-10
67+
68+
No significant changes.
69+
70+
71+
## [0.0.4](https://github.com/Nagidal/hatch-semver/tree/0.0.4) - 2022-11-10
72+
73+
74+
### Development Details
75+
76+
- Plugin structure is ready, should know how to bump major, minor, patch [#2](https://github.com/Nagidal/hatch-semver/issues/2)
77+
78+
79+
### Documentation
80+
81+
- Better readme, but not final [#8](https://github.com/Nagidal/hatch-semver/issues/8)
82+
83+
84+
## [0.0.3](https://github.com/Nagidal/hatch-semver/tree/0.0.3) - 2022-11-10
85+
86+
87+
### Bugfixes
88+
89+
- Renamed module to hatch_semver [#6](https://github.com/Nagidal/hatch-semver/issues/6)
90+
91+
92+
## [0.0.2](https://github.com/Nagidal/hatch-semver/tree/0.0.2) - 2022-11-10
93+
94+
95+
### Development Details
96+
97+
- Prepared project [#1](https://github.com/Nagidal/hatch-semver/issues/1)
98+
99+
100+
### Bugfixes
101+
102+
- Fixed plugin hook path [#4](https://github.com/Nagidal/hatch-semver/issues/4)
103+
104+

‎user-docs/README.md‎ renamed to ‎docs/README.md‎

File renamed without changes.

‎user-docs/CHANGELOG.md‎ renamed to ‎docs/user-docs/CHANGELOG.md‎

File renamed without changes.

‎docs/user-docs/README.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# hatch-semver
2+
3+
A plugin for [hatch][hatch] to support [semantic versioning][semver]. Hatch-semver relies on [python-semver][python-semver] for all the versioning logic.
4+
5+
## Setup
6+
7+
Introduce hatch-semver as a build-dependency to your project (in your `pyproject.toml`):
8+
9+
```toml
10+
[build-system]
11+
requires = [
12+
"hatchling>=1.8.0",
13+
"hatch-semver",
14+
]
15+
build-backend = "hatchling.build"
16+
```
17+
18+
Further down in `pyproject.toml`,
19+
where you set up the *hatch version* command,
20+
set version scheme to `semver`:
21+
```toml
22+
[tool.hatch.version]
23+
path = "src/<your_project>/__about__.py"
24+
validate-bump = True
25+
scheme = "semver"
26+
```
27+
28+
### Beware
29+
30+
Hatch-semver plugin will only work with project versions which can be readily parsed by [python-semver][python-semver].
31+
Therefore, if you are introducing hatch-semver into an existing project, you must **make sure that the project's current version is a valid semantic version.**
32+
You can test that [here][semver-regex].
33+
34+
## Quick Start
35+
36+
Many of hatch's [standard versioning][hatch_versioning] commands also work for hatch-semver to bump your project's version in a semver-compliant way.
37+
Such command is written as a single string of comma-separated bump instructions as a positional argument of the `hatch version` subcommand, i.e `hatch version <COMMAND>`.
38+
39+
Starting with `0.1.0` as the original version, here is a series of example commands which illustrate some common ways how to bump the version:
40+
41+
| Old Version | Command | New Version |
42+
| ---------------------- | ------------------- | -------------------- |
43+
| `0.1.0` | `patch` | `0.1.1` |
44+
| `0.1.1` | `minor,patch,patch` | `0.2.2` |
45+
| `0.2.2` | `minor` | `0.3.0` |
46+
| `0.3.0` | `rc` | `0.3.1-rc.1` |
47+
| `0.3.1-rc.1` | `rc` | `0.3.1-rc.2` |
48+
| `0.3.1-rc.2` | `release` | `0.3.1` |
49+
| `0.3.1` | `0.9.5` | `0.9.5` |
50+
| `0.9.5` | `major,rc` | `1.0.0-rc.1` |
51+
| `1.0.0-rc.1` | `release` | `1.0.0` |
52+
53+
See the [command reference][commands] for all the commands in full detail. If you are familiar with hatch's standard versioning scheme, perhaps a [comparison][comparison] of the standard scheme and hatch-semver will be of interest.
54+
55+
56+
[hatch]: https://hatch.pypa.io/
57+
[hatch_versioning]: https://hatch.pypa.io/latest/version/#updating
58+
[python-semver]: https://github.com/python-semver/python-semver/tree/maint/v2
59+
[semver-regex]: https://regex101.com/r/Ly7O1x/3/
60+
[semver]: https://semver.org/
61+
[commands]: user_guide/1-commands.md
62+
[comparison]: user_guide/2-migrating-to-semver.md

‎user-docs/user_guide/1-commands.md‎ renamed to ‎docs/user-docs/user_guide/1-commands.md‎

File renamed without changes.

‎user-docs/user_guide/2-migrating-to-semver.md‎ renamed to ‎docs/user-docs/user_guide/2-migrating-to-semver.md‎

File renamed without changes.

‎docs/user_guide/1-commands.md‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
# Commands
2+
3+
A hatch-semver command is written as a single string of comma-separated bump instructions as the single positional argument of the `hatch version` subcommand, i.e `hatch version <COMMAND>`.
4+
5+
6+
## No Command At All
7+
8+
If no command is given, `hatch version` will simply return the current version of the project.
9+
10+
## Specific Version
11+
12+
You can set a specific version directly, as long as it is a [semantic version][semver-regex]. If [bump validation][validation] is used, the resulting version must also be higher, or—if only the build identifier changes—at least equal in precedence.
13+
14+
| Old Version | Command | validate-bump | New Version |
15+
| ---------------------- | ------------------- | ------------- | -------------------- |
16+
| `2.3.4` | `13.5.26` | True | `13.5.26` |
17+
| `2.3.4` | `2.3.3` | True | ValidationError |
18+
| `2.3.4` | `2.3.3` | False | `2.3.3` |
19+
| `2.3.4` | `2.3.4-alpha` | True | ValidationError |
20+
| `2.3.4` | `2.3.4-alpha` | False | `2.3.4-alpha` |
21+
| `2.3.4-alpha` | `2.3.4` | True | `2.3.4` |
22+
| `3.0.0-beta.2` | `3.0.0-almost-done.3` | True | ValidationError |
23+
| `3.0.0-beta.2` | `3.0.0-rc.1` | True | `3.0.0-rc.1` |
24+
| `4.3.2-rc.2+zoom` | `4.3.2-rc.2+dev` | True | `4.3.2-rc.2+dev` |
25+
26+
Keep in mind that all pre-releases are ranked by their ASCII sort order and all of them are lower in precedence than the associated normal version, hence the validation errors.
27+
Build versions have all the same precedence, hence no validation error.
28+
29+
## Major, Minor, Patch
30+
31+
| Old Version | Command | New Version |
32+
| ---------------------- | ------------------- | -------------------- |
33+
| `0.1.0` | `patch`<br>`fix`<br>`micro` | `0.1.1` |
34+
| `0.1.1` | `minor` | `0.2.0` |
35+
| `1.0.0` | `major` | `1.0.0` |
36+
37+
These commands bump the [version core][bnf]. `fix` and `micro` are aliases of `patch`.
38+
39+
[Pre-release][pre] and [build][build] commands allow specifying their value with `=`.
40+
This, however, is not possible for the version core bump commands.
41+
To accomplish bigger version bumps, they can be [chained][chained-commands] [together][chained-pre] or replaced by a [specific version][specific-version].
42+
43+
| Old Version | Command | New Version |
44+
| ---------------------- | ------------------- | -------------------- |
45+
| `0.1.0` | `major=7,minor=27` | ValueError |
46+
| `0.1.0` | `7.27.6` | `7.27.6` |
47+
| `0.1.0` | `fix,fix,fix,fix` | `0.1.4` |
48+
| `0.1.0` | `major,major,minor` | `2.1.0` |
49+
50+
## Pre-Release
51+
52+
If applied on a version without [pre-release identifiers][bnf], `prerelease`—or its aliases `rc`, `pre`, `pre-release`—**will bump the patch version** and introduce the default pre-release identifiers *rc* and *1*.
53+
If some pre-release identifiers are already present and the last one is a number, it will be bumped. Naturally, this drops any present build identifiers.
54+
55+
| Old Version | Command | New Version |
56+
| ---------------------- | ------------------- | -------------------- |
57+
| `0.9.5` | `prerelease`<br>`rc`<br>`pre`<br>`pre-release` | `0.9.6-rc.1` |
58+
| `0.9.5-rc.1` | `pre` | `0.9.5-rc.2` |
59+
| `0.9.5-rc.2+debug` | `rc` | `0.9.5-rc.3` |
60+
| `0.9.5+dev.3` | `rc` | `0.9.6-rc.1` |
61+
62+
### Chained With a Version Core Bump
63+
64+
You can [chain][chained-commands] multiple commands together.
65+
If the [version core][bnf] is bumped before the pre-release bump, the pre-release bump **will not bump the patch version**.
66+
67+
| Old Version | Command | New Version |
68+
| ---------------------- | ------------------- | -------------------- |
69+
| `0.8.6` | `rc` | `0.8.7-rc.1` |
70+
| `0.8.6` | `patch,rc` | `0.8.7-rc.1` |
71+
| `0.8.6` | `minor,rc` | `0.9.0-rc.1` |
72+
| `0.8.6` | `major,rc` | `1.0.0-rc.1` |
73+
| `0.8.6` | `1.3.5,rc,rc` | `1.3.5-rc.2` |
74+
| `0.8.6` | `major,rc,build` | `1.0.0-rc.1+build.1` |
75+
| `0.8.6` | `major,build,rc` | `1.0.0-rc.1` |
76+
77+
### Alphanumeric Pre-Release Identifiers
78+
79+
If pre-release identifiers are present but the last one is an [alphanumeric identifier][bnf]—i.e. not a number—it **will not be bumped** and no further identifiers are introduced (current [python-semver][python-semver] behavior).
80+
This will normally result in a `ValidationError`, unless you have turned off [validate-bump][validation] in your hatch version settings.
81+
82+
| Old Version | Command | validate-bump | New Version |
83+
| ---------------------- | ------------------- | ------------- | -------------------- |
84+
| `0.9.7-rc1` | `prerelease` | True | ValidationError |
85+
| `0.9.7-rc1` | `prerelease` | False | `0.9.7-rc1` |
86+
87+
### Custom Identifiers
88+
89+
You can define your own pre-release identifier like this: `prerelease=<identifier>`:
90+
91+
| Old Version | Command | New Version |
92+
| ---------------------- | -------------------- | -------------------- |
93+
| `0.3.3` | `pre=alpha` | `0.3.4-alpha.1` |
94+
| `0.3.4-alpha.1` | `pre` | `0.3.4-alpha.2` |
95+
| `0.3.4-alpha.2` | `pre=beta` | `0.3.4-alpha.3` <sup>[bug][bug]</sup> |
96+
97+
Unfortunately, once a pre-release identifier has been introduced, it cannot be changed later. This is a current [python-semver bug][bug].
98+
For now you can work around it by using a [specific version][specific-version] command.
99+
Bumping the version core will effectively also drop the identifier, so then another identifier can be introduced again.
100+
101+
### Alpha, Beta Shortcuts
102+
103+
`alpha` and `beta` are very common pre-release identifiers.
104+
Hatch-semver provides the `alpha` and `beta` shortcuts for `prerelease=alpha` and `prerelease=beta`, respectively.
105+
106+
| Old Version | Command | New Version |
107+
| ---------------------- | -------------------- | -------------------- |
108+
| `5.12.3` | `alpha` | `5.12.4-alpha.1` |
109+
| `5.12.3` | `beta` | `5.12.4-beta.1` |
110+
111+
`alpha` and `beta` themselves are not *aliases* of `prerelease`.
112+
You cannot use them to define a custom identifier.
113+
`rc`, however, *is* a true alias and allows this.
114+
115+
| Old Version | Command | New Version |
116+
| ---------------------- | -------------------- | -------------------- |
117+
| `5.12.3` | `alpha=ALPHA` | ValueError |
118+
| `5.12.3` | `rc=RC` | `5.12.4-RC.1` |
119+
120+
## Release
121+
122+
The `release` command turns a pre-release version into a final release.
123+
If applied on a bare [version core][bnf], it will result in a ValidationError because the resulting version is not higher than the old one. Bump validation can be [turned off][validation].
124+
125+
| Old Version | Command | validate-bump | New Version |
126+
| ---------------------- | ------------------- | ------------- | -------------------- |
127+
| `1.0.0-rc4+build.23` | `release` | True | `1.0.0` |
128+
| `1.0.0` | `release` | True | ValidationError |
129+
| `1.0.0` | `release` | False | `1.0.0` |
130+
131+
You can meaningfully use release chained with another commands, although the alternatives are perhaps more intuitive:
132+
133+
| Old Version | Command | New Version |
134+
| ---------------------- | -------------------- | -------------------- |
135+
| `7.1.8-rc.1` | `release,beta` | `7.1.9-beta.1` |
136+
| `7.1.8-rc.1` | `patch,beta` | `7.1.9-beta.1` |
137+
138+
## Build
139+
140+
The `build` command introduces the default build identifiers *build* and *1*.
141+
If some build identifiers are already present, and the last one *is a number*, it will be bumped.
142+
143+
Similar to the [pre-release][pre] command, you can specify you own custom build idetifier after `=`.
144+
Same as with pre-releases, this is prone to a [bug in python-semver][bug].
145+
146+
| Old Version | Command | New Version |
147+
| ---------------------- | ------------------- | -------------------- |
148+
| `4.8.5-rc.2` | `build` | `4.8.5-rc.2+build.1` |
149+
| `4.8.5-rc.2+build.1` | `build` | `4.8.5-rc.2+build.2` |
150+
| `1.0.0` | `build=fix-docs` | `1.0.0+fix-docs.1` |
151+
| `1.0.0+fix-docs.1` | `build` | `1.0.0+fix-docs.2` |
152+
| `1.0.0+fix-docs.2` | `build=docs-fixed` | `1.0.0+fix-docs.3` <sup>[bug][bug]</sup> |
153+
154+
Build versions are all of the same precedence, so technically, a version bump does not occur.
155+
Normally, [bump-validation][validation] checks whether the resulting version is of the same precedence as the old one.
156+
However, if all that changes is the build identifier, a version of equal precedence is sufficient to pass the validation.
157+
158+
| Old Version | Command | validate-bump | New Version |
159+
| ---------------------- | ------------------- | ------------- | -------------------- |
160+
| `4.8.5-rc.2` | `build=tracing` | True | `4.8.5-rc.2+tracing.1` |
161+
| `4.8.5-rc.2+tracing.2` | `4.8.5-rc.2+debug` | True | `4.8.5-rc.2+debug` |
162+
163+
### Development Build Shortcut
164+
165+
Sometimes people release what they call development builds, or *dev builds*.
166+
A convenient shortcut for `build=dev` is `dev`.
167+
Similar to the [alpha and beta][ab-short] shortcuts, `dev` is not an alias, so don't try to specify a custom build identifier with it.
168+
169+
| Old Version | Command | New Version |
170+
| ---------------------- | ------------------- | -------------------- |
171+
| `2.9.3` | `build=dev` | `2.9.3+dev.1` |
172+
| `2.9.3` | `dev` | `2.9.3+dev.1` |
173+
| `2.9.3` | `dev=develop` | ValueError |
174+
175+
176+
### Alphanumeric Build Identifiers
177+
178+
Similar to [python-semver's][python-semver] inability to bump alphanumeric pre-release identifiers, alphanumeric build identifiers will also not be bumped.
179+
The returned result is the exact same version.
180+
A ValidationError is not raised because when bumping or changing build identifiers equal precedece of the old and new version is sufficient.
181+
182+
| Old Version | Command | validate-bump | New Version |
183+
| ---------------------- | ------------------- | ------------- | -------------------- |
184+
| `6.3.4-rc.2+verbose` | `build` | True | `6.3.4-rc.2+verbose` |
185+
186+
## Chained Commands
187+
188+
You can chain commands together by comma like this: `<command1>,<command2>,<command3>...`.
189+
They are executed one by one in the specified sequence. Some straight-forward and most common examples of chained commands are presented in the [pre-release][chained-pre] section.
190+
191+
The bump validation check is performed only after the last command is executed.
192+
It is therefore OK to temporarily violate the version precedence rule for the intermediate versions as long as the last resulting version passes the validation agains the old version.
193+
194+
| Old Version | Command | validate-bump | New Version |
195+
| ---------------------- | ------------------- | ------------- | -------------------- |
196+
| `8.0.4` | `major,8.0.5` | True | `8.0.5` |
197+
| `8.0.4` | `8.0.3,patch,build` | True | `8.0.4+build.1` |
198+
| `8.0.4+build.1` | `8.0.3,patch,build` | True | `8.0.4+build.1` |
199+
| `8.0.4-alpha.1` | `8.0.4,alpha,pre` | True | `8.0.4-alpha.2` |
200+
201+
202+
[validation]: https://hatch.pypa.io/latest/plugins/version-scheme/standard/#options
203+
[bnf]: https://semver.org/#backusnaur-form-grammar-for-valid-semver-versions
204+
[python-semver]: https://github.com/python-semver/python-semver
205+
[bug]: https://github.com/python-semver/python-semver/issues/339
206+
[specific-version]: #specific-version
207+
[semver-regex]: https://regex101.com/r/Ly7O1x/3/
208+
[chained-commands]: #chained-commands
209+
[chained-pre]: #chained-with-a-version-core-bump
210+
[pre]: #pre-release
211+
[ab-short]: #alpha-beta-shortcuts
212+
[build]: #build

0 commit comments

Comments
 (0)