comver 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- comver-0.2.0/LICENSE.md +1 -0
- comver-0.2.0/PKG-INFO +329 -0
- comver-0.2.0/README.md +300 -0
- comver-0.2.0/pyproject.toml +761 -0
- comver-0.2.0/src/comver/__init__.py +33 -0
- comver-0.2.0/src/comver/__main__.py +13 -0
- comver-0.2.0/src/comver/_cli.py +38 -0
- comver-0.2.0/src/comver/_parser.py +132 -0
- comver-0.2.0/src/comver/_regex/__init__.py +17 -0
- comver-0.2.0/src/comver/_regex/_process.py +41 -0
- comver-0.2.0/src/comver/_regex/match.py +83 -0
- comver-0.2.0/src/comver/_regex/semantic.py +97 -0
- comver-0.2.0/src/comver/_subcommand.py +174 -0
- comver-0.2.0/src/comver/_version.py +772 -0
- comver-0.2.0/src/comver/error.py +82 -0
- comver-0.2.0/src/comver/plugin.py +241 -0
- comver-0.2.0/src/comver/py.typed +0 -0
- comver-0.2.0/src/comver/py.typed.license +4 -0
- comver-0.2.0/src/comver/type_definitions.py +27 -0
- comver-0.2.0/tests/README.md +10 -0
comver-0.2.0/LICENSE.md
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
LICENSES/Apache-2.0.txt
|
comver-0.2.0/PKG-INFO
ADDED
|
@@ -0,0 +1,329 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: comver
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Commit-based semantic versioning - highly configurable and tag-free.
|
|
5
|
+
Author: open-nudge
|
|
6
|
+
Maintainer: open-nudge
|
|
7
|
+
License-Expression: Apache-2.0
|
|
8
|
+
Classifier: Development Status :: 2 - Pre-Alpha
|
|
9
|
+
Classifier: Intended Audience :: Developers
|
|
10
|
+
Classifier: Programming Language :: Python
|
|
11
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
15
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
16
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
17
|
+
Classifier: Typing :: Typed
|
|
18
|
+
Project-URL: Changelog, https://github.com/open-nudge/comver/blob/master/CHANGELOG.md
|
|
19
|
+
Project-URL: Documentation, https://open-nudge.github.io/comver
|
|
20
|
+
Project-URL: Homepage, https://open-nudge.github.io/comver
|
|
21
|
+
Project-URL: Issues, https://github.com/open-nudge/comver/issues
|
|
22
|
+
Project-URL: Repository, https://github.com/open-nudge/comver
|
|
23
|
+
Requires-Python: >=3.11
|
|
24
|
+
Requires-Dist: loadfig>=0.1.0
|
|
25
|
+
Requires-Dist: GitPython>=3
|
|
26
|
+
Provides-Extra: hatchling
|
|
27
|
+
Requires-Dist: hatchling>=1.27.0; extra == "hatchling"
|
|
28
|
+
Description-Content-Type: text/markdown
|
|
29
|
+
|
|
30
|
+
<!--
|
|
31
|
+
SPDX-FileCopyrightText: © 2025 open-nudge <https://github.com/open-nudge>
|
|
32
|
+
SPDX-FileContributor: szymonmaszke <github@maszke.co>
|
|
33
|
+
|
|
34
|
+
SPDX-License-Identifier: Apache-2.0
|
|
35
|
+
-->
|
|
36
|
+
|
|
37
|
+
# comver
|
|
38
|
+
|
|
39
|
+
<!-- mkdocs remove start -->
|
|
40
|
+
|
|
41
|
+
<!-- vale off -->
|
|
42
|
+
|
|
43
|
+
<!-- pyml disable-num-lines 30 line-length-->
|
|
44
|
+
|
|
45
|
+
<p align="center">
|
|
46
|
+
<em>Commit-based semantic versioning - highly configurable and tag-free.</em>
|
|
47
|
+
</p>
|
|
48
|
+
|
|
49
|
+
<div align="center">
|
|
50
|
+
|
|
51
|
+
<a href="https://pypi.org/project/comver">
|
|
52
|
+
</a>
|
|
53
|
+
<a href="https://pypi.org/project/comver">
|
|
54
|
+
</a>
|
|
55
|
+
<a href="https://opensource.org/licenses/Apache-2.0">
|
|
56
|
+
</a>
|
|
57
|
+
<a>
|
|
58
|
+
</a>
|
|
59
|
+
<a href="https://scorecard.dev/viewer/?uri=github.com/open-nudge/comver">
|
|
60
|
+
</a>
|
|
61
|
+
|
|
62
|
+
</div>
|
|
63
|
+
|
|
64
|
+
<p align="center">
|
|
65
|
+
✨ <a href="#features">Features</a>
|
|
66
|
+
🚀 <a href="#quick-start">Quick start</a>
|
|
67
|
+
📚 <a href="https://open-nudge.github.io/comver">Documentation</a>
|
|
68
|
+
🤝 <a href="#contribute">Contribute</a>
|
|
69
|
+
👍 <a href="https://github.com/open-nudge/comver/blob/main/ADOPTERS.md">Adopters</a>
|
|
70
|
+
📜 <a href="#legal">Legal</a>
|
|
71
|
+
</p>
|
|
72
|
+
<!-- vale on -->
|
|
73
|
+
|
|
74
|
+
______________________________________________________________________
|
|
75
|
+
|
|
76
|
+
<!-- mkdocs remove end -->
|
|
77
|
+
|
|
78
|
+
## Features
|
|
79
|
+
|
|
80
|
+
__comver__ is a tool for calculating __[semantic versioning](https://semver.org/)__
|
|
81
|
+
of your project __using only commit messages__ - no tags required!
|
|
82
|
+
|
|
83
|
+
- __Separation of concerns__: versioning focuses on technical aspects,
|
|
84
|
+
not marketing. You can now use tags solely for communication.
|
|
85
|
+
- __Highly configurable__: include only relevant commits by filtering via
|
|
86
|
+
`message`, `author`, `email`, __or even commit path__.
|
|
87
|
+
- __Immutable__: version is calculated directly from the commit history.
|
|
88
|
+
Tags can now be used more meaningfully (e.g., to mark a major milestone
|
|
89
|
+
or release).
|
|
90
|
+
- __Batteries-included__: integrate with [pdm](https://pdm-project.org/en/latest/),
|
|
91
|
+
[Hatch](https://hatch.pypa.io/latest/) or [uv](https://docs.astral.sh/uv/).
|
|
92
|
+
- __Verifiable__: verify that a specific version was generated from a
|
|
93
|
+
given commit chain - more resistant to tampering like
|
|
94
|
+
[dependency substitution attacks](https://docs.aws.amazon.com/codeartifact/latest/ug/dependency-substitution-attacks.html)
|
|
95
|
+
|
|
96
|
+
## Why?
|
|
97
|
+
|
|
98
|
+
Semantic versioning based on Git tags has a few limitations:
|
|
99
|
+
|
|
100
|
+
- Teams may avoid bumping the `major` version due to the
|
|
101
|
+
perceived weight of the change.
|
|
102
|
+
[__Double versioning scheme__](https://open-nudge.github.io/comver/tutorials/why);
|
|
103
|
+
one version for technical changes, another for public releases is
|
|
104
|
+
a viable mitigation.
|
|
105
|
+
- Tag creation by `bot`s (e.g. during automated releases) lead to problems
|
|
106
|
+
with `branch protection` (see [here](https://github.com/orgs/community/discussions/25305)).
|
|
107
|
+
- Not all commits are relevant for release versions
|
|
108
|
+
(e.g., CI changes, bot updates, or tooling config),
|
|
109
|
+
yet many schemes count them in. With filtering, `comver` can exclude
|
|
110
|
+
such noise.
|
|
111
|
+
- Tags are mutable by default and can be re-pointed. By calculating the version
|
|
112
|
+
based on commits, and combining it with the commit
|
|
113
|
+
`sha` and a config `checksum`, you get verifiable and reproducible results.
|
|
114
|
+
|
|
115
|
+
## Quick start
|
|
116
|
+
|
|
117
|
+
> [!NOTE]
|
|
118
|
+
> You can jump straight into the action and check `comver`
|
|
119
|
+
> [tutorials](https://open-nudge.github.io/comver/tutorials).
|
|
120
|
+
|
|
121
|
+
### Installation
|
|
122
|
+
|
|
123
|
+
```sh
|
|
124
|
+
> pip install comver
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
### Calculate version
|
|
128
|
+
|
|
129
|
+
> [!IMPORTANT]
|
|
130
|
+
> Although written in Python, comver can be used
|
|
131
|
+
> with any programming language.
|
|
132
|
+
|
|
133
|
+
If your commits follow the Conventional Commits format, run:
|
|
134
|
+
|
|
135
|
+
```sh
|
|
136
|
+
> comver calculate
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
This will output a version string in the `MAJOR.MINOR.PATCH` format:
|
|
140
|
+
|
|
141
|
+
```sh
|
|
142
|
+
23.1.3 # Output
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
> [!IMPORTANT]
|
|
146
|
+
> You can use [plugins](https://open-nudge.github.io/comver/tutorials/plugins)
|
|
147
|
+
> to integrate this versioning scheme
|
|
148
|
+
> with [`pdm`](https://github.com/pdm-project/pdm) or
|
|
149
|
+
> [`hatch`](https://github.com/pypa/hatch). More below!
|
|
150
|
+
|
|
151
|
+
<!-- mkdocs remove start -->
|
|
152
|
+
|
|
153
|
+
### Configuration
|
|
154
|
+
|
|
155
|
+
Configuration can be done either in `pyproject.toml`
|
|
156
|
+
(recommended for `Python`-first project) or in a separate
|
|
157
|
+
`.comver.toml` file (recommended for non-python projects):
|
|
158
|
+
|
|
159
|
+
<table>
|
|
160
|
+
<tr>
|
|
161
|
+
<th>pyproject.toml</th>
|
|
162
|
+
<th>.comver.toml</th>
|
|
163
|
+
</tr>
|
|
164
|
+
<tr>
|
|
165
|
+
<td>
|
|
166
|
+
|
|
167
|
+
```toml
|
|
168
|
+
[tool.comver]
|
|
169
|
+
# Only commits to these paths are considered
|
|
170
|
+
path_includes = [
|
|
171
|
+
"src/*",
|
|
172
|
+
"pyproject.toml",
|
|
173
|
+
]
|
|
174
|
+
|
|
175
|
+
# Commits done by GitHub Actions bot are discarded
|
|
176
|
+
author_name_excludes = [
|
|
177
|
+
"github-actions[bot]",
|
|
178
|
+
]
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
</td>
|
|
182
|
+
<td>
|
|
183
|
+
|
|
184
|
+
```toml
|
|
185
|
+
# No [tool.comver] needed here
|
|
186
|
+
# Source only commits considered
|
|
187
|
+
path_includes = [
|
|
188
|
+
"src/*",
|
|
189
|
+
]
|
|
190
|
+
|
|
191
|
+
# Commits messages with [no version] are discarded
|
|
192
|
+
message_excludes = [
|
|
193
|
+
".*\[no version\].*",
|
|
194
|
+
".*\[skipversion\].*",
|
|
195
|
+
]
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
</td>
|
|
199
|
+
</tr>
|
|
200
|
+
</table>
|
|
201
|
+
|
|
202
|
+
> [!TIP]
|
|
203
|
+
> See suggested configuration examples [here](https://open-nudge.github.io/comver/tutorials/configuration)
|
|
204
|
+
|
|
205
|
+
### Integrations
|
|
206
|
+
|
|
207
|
+
> [!NOTE]
|
|
208
|
+
> You can use `comver` with [`uv`](https://github.com/astral-sh/uv)
|
|
209
|
+
> by selecting the appropriate [build backend](https://docs.astral.sh/uv/concepts/build-backend/#choosing-a-build-backend),
|
|
210
|
+
> such as `hatchling`.
|
|
211
|
+
|
|
212
|
+
To integrate `comver` with [`pdm`](https://pdm-project.org/en/latest/)
|
|
213
|
+
or [`hatch`](https://hatch.pypa.io/latest/) add the following to
|
|
214
|
+
your `pyproject.toml`:
|
|
215
|
+
|
|
216
|
+
<table>
|
|
217
|
+
<tr>
|
|
218
|
+
<th>PDM</th>
|
|
219
|
+
<th>Hatch</th>
|
|
220
|
+
</tr>
|
|
221
|
+
<tr>
|
|
222
|
+
<td>
|
|
223
|
+
|
|
224
|
+
```toml
|
|
225
|
+
# Register comver for the build process
|
|
226
|
+
[build-system]
|
|
227
|
+
build-backend = "pdm.backend"
|
|
228
|
+
|
|
229
|
+
requires = [
|
|
230
|
+
"pdm-backend",
|
|
231
|
+
"comver>=0.1.0",
|
|
232
|
+
]
|
|
233
|
+
|
|
234
|
+
# Setup versioning for PDM
|
|
235
|
+
[tool.pdm.version]
|
|
236
|
+
source = "call"
|
|
237
|
+
getter = "comver.plugin:pdm"
|
|
238
|
+
|
|
239
|
+
# Comver-specific settings
|
|
240
|
+
[tool.comver]
|
|
241
|
+
...
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
</td>
|
|
245
|
+
<td>
|
|
246
|
+
|
|
247
|
+
```toml
|
|
248
|
+
# Register comver for the build process
|
|
249
|
+
[build-system]
|
|
250
|
+
build-backend = "hatchling.build"
|
|
251
|
+
|
|
252
|
+
requires = [
|
|
253
|
+
"comver>=0.1.0",
|
|
254
|
+
"hatchling",
|
|
255
|
+
]
|
|
256
|
+
|
|
257
|
+
# Setup versioning for Hatchling
|
|
258
|
+
[tool.hatch.version]
|
|
259
|
+
source = "comver"
|
|
260
|
+
|
|
261
|
+
|
|
262
|
+
# Comver-specific settings
|
|
263
|
+
[tool.comver]
|
|
264
|
+
...
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
</td>
|
|
268
|
+
</tr>
|
|
269
|
+
</table>
|
|
270
|
+
|
|
271
|
+
> [!TIP]
|
|
272
|
+
> See more in the [documentation](https://open-nudge.github.io/comver/tutorials/plugins)
|
|
273
|
+
|
|
274
|
+
### Verification
|
|
275
|
+
|
|
276
|
+
To verify that a version was produced from the same Git tree and configuration,
|
|
277
|
+
first use the calculate command with additional flags:
|
|
278
|
+
|
|
279
|
+
```sh
|
|
280
|
+
comver calculate --sha --checksum
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
This outputs three space-separated values:
|
|
284
|
+
|
|
285
|
+
```sh
|
|
286
|
+
<VERSION> <SHA> <CHECKSUM>
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
> [!TIP]
|
|
290
|
+
> Append `--format=json` for machine-friendly output
|
|
291
|
+
|
|
292
|
+
Before the next release provide these values to the `comver verify`
|
|
293
|
+
to ensure the version was previously generated from the
|
|
294
|
+
same codebase and config:
|
|
295
|
+
|
|
296
|
+
```sh
|
|
297
|
+
comver verify <VERSION> <SHA> <CHECKSUM>
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
If inconsistencies are found, you'll receive feedback, for example:
|
|
301
|
+
|
|
302
|
+
> Provided checksum and the checksum of configuration do not match.
|
|
303
|
+
|
|
304
|
+
> [!TIP]
|
|
305
|
+
> Explore verification workflows in the [tutorials](https://open-nudge.github.io/comver/tutorials/verification)
|
|
306
|
+
|
|
307
|
+
<!-- md-dead-link-check: off -->
|
|
308
|
+
|
|
309
|
+
## Contribute
|
|
310
|
+
|
|
311
|
+
We welcome your contributions! Start here:
|
|
312
|
+
|
|
313
|
+
- [Code of Conduct](/CODE_OF_CONDUCT.md)
|
|
314
|
+
- [Contributing Guide](/CONTRIBUTING.md)
|
|
315
|
+
- [Roadmap](/ROADMAP.md)
|
|
316
|
+
- [Changelog](/CHANGELOG.md)
|
|
317
|
+
- [Report security vulnerabilities](/SECURITY.md)
|
|
318
|
+
- [Open an Issue](https://github.com/open-nudge/comver/issues)
|
|
319
|
+
|
|
320
|
+
## Legal
|
|
321
|
+
|
|
322
|
+
- This project is licensed under the _Apache 2.0 License_ - see
|
|
323
|
+
the [LICENSE](/LICENSE.md) file for details.
|
|
324
|
+
- This project is copyrighted by _open-nudge_ - the
|
|
325
|
+
appropriate copyright notice is included in each file.
|
|
326
|
+
|
|
327
|
+
<!-- mkdocs remove end -->
|
|
328
|
+
|
|
329
|
+
<!-- md-dead-link-check: on -->
|
comver-0.2.0/README.md
ADDED
|
@@ -0,0 +1,300 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
SPDX-FileCopyrightText: © 2025 open-nudge <https://github.com/open-nudge>
|
|
3
|
+
SPDX-FileContributor: szymonmaszke <github@maszke.co>
|
|
4
|
+
|
|
5
|
+
SPDX-License-Identifier: Apache-2.0
|
|
6
|
+
-->
|
|
7
|
+
|
|
8
|
+
# comver
|
|
9
|
+
|
|
10
|
+
<!-- mkdocs remove start -->
|
|
11
|
+
|
|
12
|
+
<!-- vale off -->
|
|
13
|
+
|
|
14
|
+
<!-- pyml disable-num-lines 30 line-length-->
|
|
15
|
+
|
|
16
|
+
<p align="center">
|
|
17
|
+
<em>Commit-based semantic versioning - highly configurable and tag-free.</em>
|
|
18
|
+
</p>
|
|
19
|
+
|
|
20
|
+
<div align="center">
|
|
21
|
+
|
|
22
|
+
<a href="https://pypi.org/project/comver">
|
|
23
|
+
</a>
|
|
24
|
+
<a href="https://pypi.org/project/comver">
|
|
25
|
+
</a>
|
|
26
|
+
<a href="https://opensource.org/licenses/Apache-2.0">
|
|
27
|
+
</a>
|
|
28
|
+
<a>
|
|
29
|
+
</a>
|
|
30
|
+
<a href="https://scorecard.dev/viewer/?uri=github.com/open-nudge/comver">
|
|
31
|
+
</a>
|
|
32
|
+
|
|
33
|
+
</div>
|
|
34
|
+
|
|
35
|
+
<p align="center">
|
|
36
|
+
✨ <a href="#features">Features</a>
|
|
37
|
+
🚀 <a href="#quick-start">Quick start</a>
|
|
38
|
+
📚 <a href="https://open-nudge.github.io/comver">Documentation</a>
|
|
39
|
+
🤝 <a href="#contribute">Contribute</a>
|
|
40
|
+
👍 <a href="https://github.com/open-nudge/comver/blob/main/ADOPTERS.md">Adopters</a>
|
|
41
|
+
📜 <a href="#legal">Legal</a>
|
|
42
|
+
</p>
|
|
43
|
+
<!-- vale on -->
|
|
44
|
+
|
|
45
|
+
______________________________________________________________________
|
|
46
|
+
|
|
47
|
+
<!-- mkdocs remove end -->
|
|
48
|
+
|
|
49
|
+
## Features
|
|
50
|
+
|
|
51
|
+
__comver__ is a tool for calculating __[semantic versioning](https://semver.org/)__
|
|
52
|
+
of your project __using only commit messages__ - no tags required!
|
|
53
|
+
|
|
54
|
+
- __Separation of concerns__: versioning focuses on technical aspects,
|
|
55
|
+
not marketing. You can now use tags solely for communication.
|
|
56
|
+
- __Highly configurable__: include only relevant commits by filtering via
|
|
57
|
+
`message`, `author`, `email`, __or even commit path__.
|
|
58
|
+
- __Immutable__: version is calculated directly from the commit history.
|
|
59
|
+
Tags can now be used more meaningfully (e.g., to mark a major milestone
|
|
60
|
+
or release).
|
|
61
|
+
- __Batteries-included__: integrate with [pdm](https://pdm-project.org/en/latest/),
|
|
62
|
+
[Hatch](https://hatch.pypa.io/latest/) or [uv](https://docs.astral.sh/uv/).
|
|
63
|
+
- __Verifiable__: verify that a specific version was generated from a
|
|
64
|
+
given commit chain - more resistant to tampering like
|
|
65
|
+
[dependency substitution attacks](https://docs.aws.amazon.com/codeartifact/latest/ug/dependency-substitution-attacks.html)
|
|
66
|
+
|
|
67
|
+
## Why?
|
|
68
|
+
|
|
69
|
+
Semantic versioning based on Git tags has a few limitations:
|
|
70
|
+
|
|
71
|
+
- Teams may avoid bumping the `major` version due to the
|
|
72
|
+
perceived weight of the change.
|
|
73
|
+
[__Double versioning scheme__](https://open-nudge.github.io/comver/tutorials/why);
|
|
74
|
+
one version for technical changes, another for public releases is
|
|
75
|
+
a viable mitigation.
|
|
76
|
+
- Tag creation by `bot`s (e.g. during automated releases) lead to problems
|
|
77
|
+
with `branch protection` (see [here](https://github.com/orgs/community/discussions/25305)).
|
|
78
|
+
- Not all commits are relevant for release versions
|
|
79
|
+
(e.g., CI changes, bot updates, or tooling config),
|
|
80
|
+
yet many schemes count them in. With filtering, `comver` can exclude
|
|
81
|
+
such noise.
|
|
82
|
+
- Tags are mutable by default and can be re-pointed. By calculating the version
|
|
83
|
+
based on commits, and combining it with the commit
|
|
84
|
+
`sha` and a config `checksum`, you get verifiable and reproducible results.
|
|
85
|
+
|
|
86
|
+
## Quick start
|
|
87
|
+
|
|
88
|
+
> [!NOTE]
|
|
89
|
+
> You can jump straight into the action and check `comver`
|
|
90
|
+
> [tutorials](https://open-nudge.github.io/comver/tutorials).
|
|
91
|
+
|
|
92
|
+
### Installation
|
|
93
|
+
|
|
94
|
+
```sh
|
|
95
|
+
> pip install comver
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### Calculate version
|
|
99
|
+
|
|
100
|
+
> [!IMPORTANT]
|
|
101
|
+
> Although written in Python, comver can be used
|
|
102
|
+
> with any programming language.
|
|
103
|
+
|
|
104
|
+
If your commits follow the Conventional Commits format, run:
|
|
105
|
+
|
|
106
|
+
```sh
|
|
107
|
+
> comver calculate
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
This will output a version string in the `MAJOR.MINOR.PATCH` format:
|
|
111
|
+
|
|
112
|
+
```sh
|
|
113
|
+
23.1.3 # Output
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
> [!IMPORTANT]
|
|
117
|
+
> You can use [plugins](https://open-nudge.github.io/comver/tutorials/plugins)
|
|
118
|
+
> to integrate this versioning scheme
|
|
119
|
+
> with [`pdm`](https://github.com/pdm-project/pdm) or
|
|
120
|
+
> [`hatch`](https://github.com/pypa/hatch). More below!
|
|
121
|
+
|
|
122
|
+
<!-- mkdocs remove start -->
|
|
123
|
+
|
|
124
|
+
### Configuration
|
|
125
|
+
|
|
126
|
+
Configuration can be done either in `pyproject.toml`
|
|
127
|
+
(recommended for `Python`-first project) or in a separate
|
|
128
|
+
`.comver.toml` file (recommended for non-python projects):
|
|
129
|
+
|
|
130
|
+
<table>
|
|
131
|
+
<tr>
|
|
132
|
+
<th>pyproject.toml</th>
|
|
133
|
+
<th>.comver.toml</th>
|
|
134
|
+
</tr>
|
|
135
|
+
<tr>
|
|
136
|
+
<td>
|
|
137
|
+
|
|
138
|
+
```toml
|
|
139
|
+
[tool.comver]
|
|
140
|
+
# Only commits to these paths are considered
|
|
141
|
+
path_includes = [
|
|
142
|
+
"src/*",
|
|
143
|
+
"pyproject.toml",
|
|
144
|
+
]
|
|
145
|
+
|
|
146
|
+
# Commits done by GitHub Actions bot are discarded
|
|
147
|
+
author_name_excludes = [
|
|
148
|
+
"github-actions[bot]",
|
|
149
|
+
]
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
</td>
|
|
153
|
+
<td>
|
|
154
|
+
|
|
155
|
+
```toml
|
|
156
|
+
# No [tool.comver] needed here
|
|
157
|
+
# Source only commits considered
|
|
158
|
+
path_includes = [
|
|
159
|
+
"src/*",
|
|
160
|
+
]
|
|
161
|
+
|
|
162
|
+
# Commits messages with [no version] are discarded
|
|
163
|
+
message_excludes = [
|
|
164
|
+
".*\[no version\].*",
|
|
165
|
+
".*\[skipversion\].*",
|
|
166
|
+
]
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
</td>
|
|
170
|
+
</tr>
|
|
171
|
+
</table>
|
|
172
|
+
|
|
173
|
+
> [!TIP]
|
|
174
|
+
> See suggested configuration examples [here](https://open-nudge.github.io/comver/tutorials/configuration)
|
|
175
|
+
|
|
176
|
+
### Integrations
|
|
177
|
+
|
|
178
|
+
> [!NOTE]
|
|
179
|
+
> You can use `comver` with [`uv`](https://github.com/astral-sh/uv)
|
|
180
|
+
> by selecting the appropriate [build backend](https://docs.astral.sh/uv/concepts/build-backend/#choosing-a-build-backend),
|
|
181
|
+
> such as `hatchling`.
|
|
182
|
+
|
|
183
|
+
To integrate `comver` with [`pdm`](https://pdm-project.org/en/latest/)
|
|
184
|
+
or [`hatch`](https://hatch.pypa.io/latest/) add the following to
|
|
185
|
+
your `pyproject.toml`:
|
|
186
|
+
|
|
187
|
+
<table>
|
|
188
|
+
<tr>
|
|
189
|
+
<th>PDM</th>
|
|
190
|
+
<th>Hatch</th>
|
|
191
|
+
</tr>
|
|
192
|
+
<tr>
|
|
193
|
+
<td>
|
|
194
|
+
|
|
195
|
+
```toml
|
|
196
|
+
# Register comver for the build process
|
|
197
|
+
[build-system]
|
|
198
|
+
build-backend = "pdm.backend"
|
|
199
|
+
|
|
200
|
+
requires = [
|
|
201
|
+
"pdm-backend",
|
|
202
|
+
"comver>=0.1.0",
|
|
203
|
+
]
|
|
204
|
+
|
|
205
|
+
# Setup versioning for PDM
|
|
206
|
+
[tool.pdm.version]
|
|
207
|
+
source = "call"
|
|
208
|
+
getter = "comver.plugin:pdm"
|
|
209
|
+
|
|
210
|
+
# Comver-specific settings
|
|
211
|
+
[tool.comver]
|
|
212
|
+
...
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
</td>
|
|
216
|
+
<td>
|
|
217
|
+
|
|
218
|
+
```toml
|
|
219
|
+
# Register comver for the build process
|
|
220
|
+
[build-system]
|
|
221
|
+
build-backend = "hatchling.build"
|
|
222
|
+
|
|
223
|
+
requires = [
|
|
224
|
+
"comver>=0.1.0",
|
|
225
|
+
"hatchling",
|
|
226
|
+
]
|
|
227
|
+
|
|
228
|
+
# Setup versioning for Hatchling
|
|
229
|
+
[tool.hatch.version]
|
|
230
|
+
source = "comver"
|
|
231
|
+
|
|
232
|
+
|
|
233
|
+
# Comver-specific settings
|
|
234
|
+
[tool.comver]
|
|
235
|
+
...
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
</td>
|
|
239
|
+
</tr>
|
|
240
|
+
</table>
|
|
241
|
+
|
|
242
|
+
> [!TIP]
|
|
243
|
+
> See more in the [documentation](https://open-nudge.github.io/comver/tutorials/plugins)
|
|
244
|
+
|
|
245
|
+
### Verification
|
|
246
|
+
|
|
247
|
+
To verify that a version was produced from the same Git tree and configuration,
|
|
248
|
+
first use the calculate command with additional flags:
|
|
249
|
+
|
|
250
|
+
```sh
|
|
251
|
+
comver calculate --sha --checksum
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
This outputs three space-separated values:
|
|
255
|
+
|
|
256
|
+
```sh
|
|
257
|
+
<VERSION> <SHA> <CHECKSUM>
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
> [!TIP]
|
|
261
|
+
> Append `--format=json` for machine-friendly output
|
|
262
|
+
|
|
263
|
+
Before the next release provide these values to the `comver verify`
|
|
264
|
+
to ensure the version was previously generated from the
|
|
265
|
+
same codebase and config:
|
|
266
|
+
|
|
267
|
+
```sh
|
|
268
|
+
comver verify <VERSION> <SHA> <CHECKSUM>
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
If inconsistencies are found, you'll receive feedback, for example:
|
|
272
|
+
|
|
273
|
+
> Provided checksum and the checksum of configuration do not match.
|
|
274
|
+
|
|
275
|
+
> [!TIP]
|
|
276
|
+
> Explore verification workflows in the [tutorials](https://open-nudge.github.io/comver/tutorials/verification)
|
|
277
|
+
|
|
278
|
+
<!-- md-dead-link-check: off -->
|
|
279
|
+
|
|
280
|
+
## Contribute
|
|
281
|
+
|
|
282
|
+
We welcome your contributions! Start here:
|
|
283
|
+
|
|
284
|
+
- [Code of Conduct](/CODE_OF_CONDUCT.md)
|
|
285
|
+
- [Contributing Guide](/CONTRIBUTING.md)
|
|
286
|
+
- [Roadmap](/ROADMAP.md)
|
|
287
|
+
- [Changelog](/CHANGELOG.md)
|
|
288
|
+
- [Report security vulnerabilities](/SECURITY.md)
|
|
289
|
+
- [Open an Issue](https://github.com/open-nudge/comver/issues)
|
|
290
|
+
|
|
291
|
+
## Legal
|
|
292
|
+
|
|
293
|
+
- This project is licensed under the _Apache 2.0 License_ - see
|
|
294
|
+
the [LICENSE](/LICENSE.md) file for details.
|
|
295
|
+
- This project is copyrighted by _open-nudge_ - the
|
|
296
|
+
appropriate copyright notice is included in each file.
|
|
297
|
+
|
|
298
|
+
<!-- mkdocs remove end -->
|
|
299
|
+
|
|
300
|
+
<!-- md-dead-link-check: on -->
|