feat: create initial release

.pre-commit-config.yaml

@@ -34,7 +34,7 @@ repos:
         entry: "conform enforce"
         pass_filenames: false
   - repo: "https://github.com/trufflesecurity/trufflehog"
-    rev: "907ac64fd42b18dab2ceba2fda39834d3f8ba7e3"  # frozen: v3.90.1
+    rev: "a05cf0859455b5b16317ee22d809887a4043cdf0"  # frozen: v3.90.2
     hooks:
       - id: "trufflehog"
         alias: "secrets"

.vale.ini

@@ -15,6 +15,7 @@ RedHat.ReadabilityGrade = NO
 RedHat.GitLinks = NO
 Vale.Spelling = NO
 write-good.Passive = NO
+RedHat.TermsErrors = NO
 
 [*.md]
 proselint.Annotations = NO
@@ -27,6 +28,8 @@ RedHat.Spacing = NO
 RedHat.PassiveVoice = NO
 RedHat.Definitions = NO
 write-good.E-Prime = NO
+# Ignored because of mismatches with regex
+RedHat.TermsErrors = NO
 
 [{DCO.md,docs/DCO.md,LICENSE.md,docs/LICENSE.md}]
 BasedOnStyles = Vale

README.md

@@ -48,71 +48,232 @@ ______________________________________________________________________
 
 ## Features
 
-__comver__ is a … allowing you to:
-
-- __Feature 1__: Description of the feature
-- __Feature 2__: Description of the feature
-- __Feature 3__: Description of the feature
-- __Feature 4__: Description of the feature
-- __Feature 5__: Description of the feature
+__comver__ is a tool for calculating __[semantic versioning](https://semver.org/)__
+of your project __using only commit messages__ - no tags required!
+
+- __Separation of concerns__: versioning focuses on technical aspects,
+    not marketing. You can now use tags solely for communication.
+- __Highly configurable__: include only relevant commits by filtering via
+    `message`, `author`, `email`, __or even commit path__.
+- __Immutable__: version is calculated directly from the commit history.
+    Tags can now be used more meaningfully (e.g., to mark a major milestone
+    or release).
+- __Batteries-included__: integrate with [pdm](https://pdm-project.org/en/latest/),
+    [Hatch](https://hatch.pypa.io/latest/) or [uv](https://docs.astral.sh/uv/).
+- __Verifiable__: verify that a specific version was generated from a
+    given commit chain - more resistant to tampering like
+    [dependency substitution attacks](https://docs.aws.amazon.com/codeartifact/latest/ug/dependency-substitution-attacks.html)
+
+## Why?
+
+Semantic versioning based on Git tags has a few limitations:
+
+- Teams may avoid bumping the `major` version due to the
+    perceived weight of the change.
+    [__Double versioning scheme__](https://open-nudge.github.io/comver/tutorials/why);
+    one version for technical changes, another for public releases is
+    a viable mitigation.
+- Not all commits are relevant for release versions
+    (e.g., CI changes, bot updates, or tooling config),
+    yet many schemes count them in. With filtering, `comver` can exclude
+    such noise.
+- Tags are mutable by default and can be re-pointed. By calculating the version
+    based on commits, and combining it with the commit
+    `sha` and a config `checksum`, you get verifiable and reproducible results.
 
 ## Quick start
 
+> [!NOTE]
+> You can jump straight into the action and check `comver`
+> [tutorials](https://open-nudge.github.io/comver/tutorials).
+
 ### Installation
 
 ```sh
 > pip install comver
 ```
 
-### Usage
+### Calculate version
+
+> [!IMPORTANT]
+> Although written in Python, comver can be used
+> with any programming language.
+
+If your commits follow the Conventional Commits format, run:
+
+```sh
+> comver calculate
+```
+
+This will output a version string in the `MAJOR.MINOR.PATCH` format:
+
+```sh
+23.1.3 # Output
+```
+
+> [!IMPORTANT]
+> You can use [plugins](https://open-nudge.github.io/comver/tutorials/plugins)
+> to integrate this versioning scheme
+> with [`pdm`](https://github.com/pdm-project/pdm) or
+> [`hatch`](https://github.com/pypa/hatch). More below!
+
+<!-- mkdocs remove start -->
+
+### Configuration
+
+Configuration can be done either in `pyproject.toml`
+(recommended for `Python`-first project) or in a separate
+`.comver.toml` file (recommended for non-python projects):
+
+<table>
+<tr>
+<th>pyproject.toml</th>
+<th>.comver.toml</th>
+</tr>
+<tr>
+<td>
+
+```toml
+[tool.comver]
+# Only commits to these paths are considered
+path_includes = [
+  "src/*",
+  "pyproject.toml",
+]
+
+# Commits done by GitHub Actions bot are discarded
+author_name_excludes = [
+  "github-actions[bot]",
+]
+```
 
-```python
-import comver
+</td>
+<td>
+
+```toml
+# No [tool.comver] needed here
+# Source only commits considered
+path_includes = [
+  "src/*",
+]
+
+# Commits messages with [no version] are discarded
+message_excludes = [
+  ".*\[no version\].*",
+  ".*\[skipversion\].*",
+]
+```
 
+</td>
+</tr>
+</table>
+
+> [!TIP]
+> See suggested configuration examples [here](https://open-nudge.github.io/comver/tutorials/configuration)
+
+### Integrations
+
+> [!NOTE]
+> You can use `comver` with [`uv`](https://github.com/astral-sh/uv)
+> by selecting the appropriate [build backend](https://docs.astral.sh/uv/concepts/build-backend/#choosing-a-build-backend),
+> such as `hatchling`.
+
+To integrate `comver` with [`pdm`](https://pdm-project.org/en/latest/)
+or [`hatch`](https://hatch.pypa.io/latest/) add the following to
+your `pyproject.toml`:
+
+<table>
+<tr>
+<th>PDM</th>
+<th>Hatch</th>
+</tr>
+<tr>
+<td>
+
+```toml
+# Register comver for the build process
+[build-system]
+build-backend = "pdm.backend"
+
+requires = [
+  "pdm-backend",
+  "comver>=0.1.0",
+]
+
+# Setup versioning for PDM
+[tool.pdm.version]
+source = "call"
+getter = "comver.plugin:pdm"
+
+# Comver-specific settings
+[tool.comver]
 ...
 ```
 
-### Examples
+</td>
+<td>
+
+```toml
+# Register comver for the build process
+[build-system]
+build-backend = "hatchling.build"
+
+requires = [
+  "comver>=0.1.0",
+  "hatchling",
+]
 
-<details>
-  <summary><b><big>Short</big></b> (click me)</summary>
-&nbsp;
+# Setup versioning for Hatchling
+[tool.hatch.version]
+source = "comver"
 
-Description of the example
 
-```python
-# Short example
+# Comver-specific settings
+[tool.comver]
+...
 ```
 
-</details>
+</td>
+</tr>
+</table>
+
+> [!TIP]
+> See more in the [documentation](https://open-nudge.github.io/comver/tutorials/plugins)
 
-<details>
-  <summary><b><big>Common</big></b> (click me)</summary>
-&nbsp;
+### Verification
 
-Description of the example
+To verify that a version was produced from the same Git tree and configuration,
+first use the calculate command with additional flags:
 
-```python
-# Common use case
+```sh
+comver calculate --sha --checksum
 ```
 
-</details>
+This outputs three space-separated values:
 
-<details>
-  <summary><b><big>Advanced</big></b> (click me)</summary>
-&nbsp;
+```sh
+<VERSION> <SHA> <CHECKSUM>
+```
+
+> [!TIP]
+> Append `--format=json` for machine-friendly output
 
-Description of the example
+Before the next release provide these values to the `comver verify`
+to ensure the version was previously generated from the
+same codebase and config:
 
-```python
-# Something advanced and cool
+```sh
+comver verify <VERSION> <SHA> <CHECKSUM>
 ```
 
-</details>
+If inconsistencies are found, you'll receive feedback, for example:
 
-<!-- md-dead-link-check: off -->
+> Provided checksum and the checksum of configuration do not match.
 
-<!-- mkdocs remove start -->
+> [!TIP]
+> Explore verification workflows in the [tutorials](https://open-nudge.github.io/comver/tutorials/verification)
+
+<!-- md-dead-link-check: off -->
 
 ## Contribute
 

ROADMAP.md

@@ -7,4 +7,11 @@ SPDX-License-Identifier: Apache-2.0
 
 # Roadmap
 
+- Obtaining public opinion
+- Creating special `pyproject.toml` treatment
+    (for example versioning only based on `[project.dependencies]`
+    subsection, __not the whole file__)
+- Design multi-comver approach (multiple releases based
+    on multiple configurations)
+
 <!-- Describe project's roadmap here. -->

docs/tutorials/.nav.yml

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: © 2025 open-nudge <https://github.com/open-nudge>
+# SPDX-FileContributor: szymonmaszke <github@maszke.co>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+---
+
+ignore: "*README.md"
+
+nav:
+  - Why comver?: "why.md"
+  - Configuration: "configuration.md"
+  - Plugins: "plugins.md"
+  - Verification: "verification.md"
+...