Metadata-Version: 2.4
Name: py-conventional-semver
Version: 1.3.2
Summary: ..a Python fork of sw4k's `conventional-semver` tool.
Author-email: Shaun Wilson <mrshaunwilson@msn.com>
License-Expression: MIT
Project-URL: Documentation, https://conventional-semver.readthedocs.io/
Project-URL: Homepage, https://github.com/wilson0x4d/conventional-semver
Project-URL: Repository, https://github.com/wilson0x4d/conventional-semver.git
Keywords: SEMVER,conventional-semver,conventional-commits,sw4k
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: hanaro>=1.0.0
Requires-Dist: jinja2>=3.1.6
Provides-Extra: dev
Requires-Dist: coverage; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: punit>=1.10.8; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file


**conventional-semver** is a [Conventional Commits](https://www.conventionalcommits.org/) processor designed to emit a [SEMVER](https://semver.org) as part of a build pipeline.

## Usage

```text
Usage:
        conventional-semver [options] [repo-path]

Options:
        --help              print usage, then exit.
        --version           print version info, then exit.
        --verbose           enable verbose (debug) output.
        --commit <hash>     indicates which commit hash to start changelog from.
        --tag <name>        indicates which tag to start changelog from.
        --changelog <file>  overrides the name of the file the changelog is written to, otherwise changelog.md is the default.
        --no-semver         disable SEMVER output to STDOUT.
        --from <version>    set the baseline semver as a single `X.Y.Z` value (e.g. `--from 1.4.0`).
        --major             SEMVER Major component will start with this value, default is 0.
        --minor             SEMVER Minor component will start with this value, default is 0.
        --patch             SEMVER Patch component will start with this value, default is 0.
        --git-path <path>   overrides the path to `git` tool, otherwise `git` must be in environment PATH.

Parameters:
        repo-path           the path of the git repository to process, if not specified defaults to working directory.
```

### Generating SEMVER

When you run **conventional-semver** from within a `git` repository, it will automatically process the log and emit a semver.

Example:

```bash
$ conventional-semver
0.1.23
```

This allows you to pull a semver into an Environment Variable, evaluate it as an Argument to another tool, or pipe it to a file/stream for additional processing:

```bash
$ export SEMVER=$(conventional-semver)
$ echo $SEMVER
0.1.23
```

#### Override Baseline SEMVER

Projects adopting Conventional Commits may need to customize the baseline SEMVER, rather than starting from `0.0.0`. This can be done in two ways:

**Using `--from`** — supply a single semver string:

```bash
$ conventional-semver --from 1.4.0
1.4.3
```

**Using `--major`, `--minor`, and `--patch`** — specify each component individually:

```bash
$ conventional-semver --from 1.4.0
1.4.3

$ conventional-semver --major 1 --minor 4 --patch 0
1.4.3
```

Only `--from` *or* the individual `--major`/`--minor`/`--patch` flags may be used; when both are supplied, `--from` takes precedence.

#### SEMVER Configuration

When run without any command-line arguments a default set of settings are used which implement a standard Conventional Commits behavior.

To customize behavior a configuration file may be created. This file can be passed in using a `--config` argument, or, placed into one of the following well-known locations (and in the following order):

* `./conventional-semver.conf` (working directory.)
* `~/.config/conventional-semver/settings.conf` (user profile `.config` directory.)
* `/etc/conventional-semver/settings.conf` (root `/etc` directory.)

The configuration file should have the following format:

```ini
# lines starting with hash (#) are comments
# empty lines, like the following, are ignored

# conventional commit "type" mappings are
# configured in a [types] section. the following
# mirrors the default configuration:
[types]
.*!=major
feat.*=minor
.*=patch

# conventional commit "footer" mappings are
# configured in a [footers] section. the following
# mirrors the default configuration:
[footers]
BREAKING[\-\.]CHANGE=major

# in each of the above sections, each line
# represents a key-value pair. the key is a regex
# and the value is a component type to be
# incremented if the regex is a match.
```

There is a sample configuration file located in this repo as `config/conventional-semver.conf` which contains additional comments and explanations, you can customize it to fit your needs and then place it at one of the well-known locations mentioned above.

## Generating CHANGELOG

To generate a CHANGELOG you specify the `--changelog [filename]` switch, this takes an optional filename argument. If no filename is provided a default filename of `./CHANGELOG` is used to emit a file into the current working directory.

Example:

```bash
$ conventional-semver --changelog
```

```bash
$ conventional-semver --changelog CHANGELOG.md
```

### CHANGELOG Templates

The CHANGELOG output is defined as a single template, this is meant to provide enough flexibility that you could emit templates in various structured formats such as XML, JSON, Markdown, reStructuredText, etc.

The default template is built-in, and is designed to produce a file that is markdown-friendly.

To specify a custom template, supply an additional `--changelog-template <template path>` argument that indicates where the template can be found:

```bash
$ conventional-semver --changelog --template ./templates/template_name.j2
```

```bash
$ conventional-semver --changelog ./CHANGELOG.rst --template ./templates/template_name.j2
```

#### Jinja2

Templates are Jinja2-based, offering a powerful feature set and a syntax familiar to the Python community.

##### Variables

Templates are provided a data dict having the following structure:

```json
{
    "name": <derived from working directory basename>,
    "semver": <semver of most recent commit>,
    "date": <date of most recent commit>,
    "hash": <git hash of most recent commit>,
    "versions": [
        {
            "semver": <semver of commit>,
            "commits": [
                {
                    "date": <commit date>,
                    "hash": <commit hash>,
                    "message": <original commit message>,
                    "type": <the `type` parsed from commit message>,
                    "scope": <the `scope` parsed from commit message>,
                    "header": <the first line parsed from the commit message, sans `type` and `scope`>,
                    "body": <optional, the `body` lines parsed from the commit message, if defined>,
                    "footers": <optional, the `trailing` lines parsed from the commit message, if defined>
                }
            ]
        }
    ]
}
```

For each SEMVER increment a `"versions"` entry is provided. A single semver increment may be the result of multiple commits, and so `"commits"` is an array of all commits related to the semver increment.  Typically, this will be a 1-to-1 relationship, but it depends on the practices and patterns of the developer/organization.

##### Example

The built-in template looks approximately like this:

```jinja2
        {% for version in versions %}
        #### {{ version.semver }}
        {% for commit in version.commits %}
        - {{ commit.type }}({{ commit.scope }}): {{ commit.header }}{% if commit.body is defined %}
        {{ commit.body }}
        {% if commit.footers is defined %}
        > {{ commit.footers }}{% endif %}{% else %}
        {% endif %}
        {%- endfor -%}{%- endfor -%}
```
