mirror of
https://github.com/lukaszraczylo/semver-generator.git
synced 2026-06-05 22:49:25 +00:00
Update documentation.
This commit is contained in:
@@ -1,69 +1,137 @@
|
||||
## Semantic version generator
|
||||
# Semantic Version Generator
|
||||
|
||||
[](https://github.com/lukaszraczylo/semver-generator/actions/workflows/release.yaml)  [](https://codecov.io/gh/lukaszraczylo/semver-generator)
|
||||
|
||||
Project created overnight, to prove that management of semantic versioning is NOT painful and do not require arguments and debates within the team. Simple, clean and only thing the project team should need to agree to are the keywords.
|
||||
A lightweight, configurable tool that simplifies semantic versioning by automatically calculating version numbers based on git commit messages. No more manual version management or team debates about versioning - just agree on the keywords and let the tool handle the rest.
|
||||
|
||||
- [Semantic version generator](#semantic-version-generator)
|
||||
- [How does it work](#how-does-it-work)
|
||||
- [Additional features](#additional-features)
|
||||
- [Important changes](#important-changes)
|
||||
- [Usage](#usage)
|
||||
- [Authentication](#authentication)
|
||||
- [As a binary](#as-a-binary)
|
||||
- [As a github action](#as-a-github-action)
|
||||
- [As a docker container](#as-a-docker-container)
|
||||
- [Calculations example \[standard\]](#calculations-example-standard)
|
||||
- [Calculations example \[strict matching\]](#calculations-example-strict-matching)
|
||||
- [Release candidates](#release-candidates)
|
||||
- [Example configuration](#example-configuration)
|
||||
- [Good to know](#good-to-know)
|
||||
## Table of Contents
|
||||
|
||||
### How does it work
|
||||
- [How It Works](#how-it-works)
|
||||
- [Key Features](#key-features)
|
||||
- [Important Changes](#important-changes)
|
||||
- [Installation](#installation)
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Binary](#binary)
|
||||
- [Docker](#docker)
|
||||
- [GitHub Action](#github-action)
|
||||
- [Usage](#usage)
|
||||
- [Authentication](#authentication)
|
||||
- [Command Line Options](#command-line-options)
|
||||
- [Configuration File](#configuration-file)
|
||||
- [Versioning Behavior](#versioning-behavior)
|
||||
- [Release Candidates](#release-candidates)
|
||||
- [Examples](#examples)
|
||||
- [Standard Mode](#standard-mode)
|
||||
- [Strict Matching Mode](#strict-matching-mode)
|
||||
- [Advanced Features](#advanced-features)
|
||||
- [Force Settings](#force-settings)
|
||||
- [Blacklist Terms](#blacklist-terms)
|
||||
- [Tips & Best Practices](#tips--best-practices)
|
||||
|
||||
* Binary clones the github repository
|
||||
* Iterates through the list of commits looking for the keywords specified in config file for additional bumps of versions
|
||||
* Returns the semantic version which can be included in the release
|
||||
## How It Works
|
||||
|
||||
### Additional features
|
||||
The semantic version generator follows a simple process:
|
||||
|
||||
* With flag `-e` or config `force.existing: true` the existing tags in versioning will be respected, helping you to avoid the version conflicts.
|
||||
* With config `force.commit: deadbeef` where `deadbeef` is the commit hash - calculations will start from the specified commit.
|
||||
1. Clones the specified GitHub repository (or uses a local repository)
|
||||
2. Iterates through the commit history, analyzing each commit message
|
||||
3. Looks for predefined keywords (configurable) that trigger version increments
|
||||
4. Calculates the appropriate semantic version based on the matches
|
||||
5. Returns the resulting version that can be used for releases
|
||||
|
||||
### Important changes
|
||||
## Key Features
|
||||
|
||||
* From version `1.4.2+` as pointed out in [issue #12](https://github.com/lukaszraczylo/semver-generator/issues/12) commits from merge will not be included in the calculations and commits themselves will bump the version on first match ( starting checks from `patch` upwards ).
|
||||
* Added support for blacklisting terms to ignore specific commits, branch names, and merge messages from version calculations.
|
||||
- **Effortless Version Calculation**: Automatically determine the appropriate version based on commit messages
|
||||
- **Configurable Keywords**: Define your own keywords for patch, minor, and major version increments
|
||||
- **Support for Existing Tags**: Option to respect existing version tags to avoid conflicts
|
||||
- **Release Candidate Support**: Generate release candidate versions with incrementing counter (e.g., `1.2.3-rc.1`)
|
||||
- **Flexible Repository Source**: Work with either local or remote Git repositories
|
||||
- **Blacklist Support**: Ignore specific commits or branch merges from version calculations
|
||||
- **Force Options**: Start calculations from a specific commit or set a minimum version
|
||||
|
||||
### Usage
|
||||
## Important Changes
|
||||
|
||||
#### Authentication
|
||||
- **Since v1.4.2+**: Commits from merge requests are no longer included in calculations
|
||||
- **Commit Matching Behavior**: Commits will bump the version on the first match (checking from `patch` upwards)
|
||||
- **Blacklist Support**: Added ability to ignore specific terms in commit messages, branch names, and merge requests
|
||||
|
||||
If you intend to use this project with remote repositories ( regardless of them being private or public ) you need to authenticate with your repository.
|
||||
To do so you can utilise the following environment variables ( they are NOT github specific, for other providers you can use the password )
|
||||
## Installation
|
||||
|
||||
### Prerequisites
|
||||
|
||||
When using with remote repositories, authentication is required. Set the following environment variables:
|
||||
|
||||
```bash
|
||||
export GITHUB_USERNAME=lukaszraczylo
|
||||
export GITHUB_TOKEN=yourPersonalApiToken
|
||||
export GITHUB_USERNAME=yourusername
|
||||
export GITHUB_TOKEN=yourpersonalapitoken
|
||||
```
|
||||
|
||||
#### As a binary
|
||||
### Binary
|
||||
|
||||
You can download latest versions of the binaries from the [release page](https://github.com/lukaszraczylo/semver-generator/releases/latest).
|
||||
Download the latest binary from the [release page](https://github.com/lukaszraczylo/semver-generator/releases/latest).
|
||||
|
||||
**Supported OS and architectures:**
|
||||
Darwin ARM64/AMD64, Linux ARM64/AMD64, Windows AMD64
|
||||
**Supported platforms**:
|
||||
- Darwin (macOS): ARM64/AMD64
|
||||
- Linux: ARM64/AMD64
|
||||
- Windows: AMD64
|
||||
|
||||
### Docker
|
||||
|
||||
```bash
|
||||
bash$ ./semver-gen generate -r https://github.com/nextapps-de/winbox
|
||||
SEMVER 9.0.10
|
||||
bash$ ./semver-gen generate -l
|
||||
SEMVER 5.1.1
|
||||
docker pull ghcr.io/lukaszraczylo/semver-generator:latest
|
||||
```
|
||||
|
||||
**Local repository flag `-l` will always take precedence over remote repository URL**
|
||||
**Supported architectures**:
|
||||
- Linux/arm64
|
||||
- Linux/amd64
|
||||
|
||||
### GitHub Action
|
||||
|
||||
Add to your GitHub workflow:
|
||||
|
||||
```yaml
|
||||
jobs:
|
||||
prepare:
|
||||
name: Preparing build context
|
||||
runs-on: ubuntu-latest
|
||||
outputs:
|
||||
RELEASE_VERSION: ${{ steps.semver.outputs.semantic_version }}
|
||||
steps:
|
||||
- name: Checkout repo
|
||||
uses: actions/checkout@v2
|
||||
with:
|
||||
fetch-depth: '0'
|
||||
- name: Semver run
|
||||
id: semver
|
||||
uses: lukaszraczylo/semver-generator@v1
|
||||
with:
|
||||
config_file: semver.yaml
|
||||
# Either use local repository
|
||||
repository_local: true
|
||||
# Or specify remote repository
|
||||
# repository_url: https://github.com/lukaszraczylo/simple-gql-client
|
||||
# github_username: ${{ secrets.GH_USERNAME }}
|
||||
# github_token: ${{ secrets.GH_TOKEN }}
|
||||
strict: false
|
||||
existing: true
|
||||
- name: Use semantic version
|
||||
run: |
|
||||
echo "Semantic version detected: ${{ steps.semver.outputs.semantic_version }}"
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Authentication
|
||||
|
||||
For remote repositories (public or private), authenticate using:
|
||||
|
||||
```bash
|
||||
export GITHUB_USERNAME=yourusername
|
||||
export GITHUB_TOKEN=yourpersonalapitoken
|
||||
```
|
||||
|
||||
### Command Line Options
|
||||
|
||||
```
|
||||
Usage:
|
||||
semver-gen generate [flags]
|
||||
semver-gen [command]
|
||||
@@ -85,86 +153,11 @@ Flags:
|
||||
-v, --version Display version
|
||||
```
|
||||
|
||||
#### As a github action
|
||||
**Note**: The `-l/--local` flag takes precedence over the repository URL.
|
||||
|
||||
```yaml
|
||||
jobs:
|
||||
prepare:
|
||||
name: Preparing build context
|
||||
runs-on: ubuntu-latest
|
||||
outputs:
|
||||
RELEASE_VERSION: ${{ steps.semver.outputs.semantic_version }}
|
||||
steps:
|
||||
- name: Checkout repo
|
||||
uses: actions/checkout@v2
|
||||
with:
|
||||
fetch-depth: '0'
|
||||
- name: Semver run
|
||||
id: semver
|
||||
uses: lukaszraczylo/semver-generator@PLACE_LATEST_TAG_HERE
|
||||
# you can also use v1 tag which _should_ automatically upgrade to latest
|
||||
# uses: lukaszraczylo/semver-generator@v1
|
||||
with:
|
||||
config_file: semver.yaml
|
||||
# either...
|
||||
repository_local: true
|
||||
# or...
|
||||
repository_url: https://github.com/lukaszraczylo/simple-gql-client
|
||||
# when using remote repository, especially with private one:
|
||||
github_username: lukaszraczylo
|
||||
github_token: MySupeRSecr3tPa$$w0rd
|
||||
strict: true
|
||||
existing: false
|
||||
- name: Semver check
|
||||
run: |
|
||||
echo "Semantic version detected: ${{ steps.semver.outputs.semantic_version }}"
|
||||
```
|
||||
### Configuration File
|
||||
|
||||
#### As a docker container
|
||||
|
||||
```bash
|
||||
docker pull ghcr.io/lukaszraczylo/semver-generator:latest
|
||||
```
|
||||
|
||||
**Docker supported architectures:**
|
||||
Linux/arm64, Linux/amd64
|
||||
|
||||
#### Calculations example [standard]
|
||||
|
||||
```bash
|
||||
- 0.0.1 - PATCH - starting commit
|
||||
- 0.0.2 - PATCH - another commit
|
||||
- 0.0.4 - PATCH - another commit with word 'Update' => DOUBLE increment PATCH
|
||||
- 0.1.0 - MINOR - after commit with word 'Change' => increment MINOR, reset PATCH
|
||||
- 0.1.1 - PATCH - additional commit
|
||||
- 1.0.1 - MAJOR - commit with word 'BREAKING' = > INCREMENT MAJOR, reset MINOR
|
||||
- 1.0.2 - PATCH - another commit
|
||||
```
|
||||
|
||||
#### Calculations example [strict matching]
|
||||
|
||||
```bash
|
||||
- 0.0.1 - PATCH - starting commit
|
||||
- 0.0.1 - PATCH - another commit
|
||||
- 0.0.1 - PATCH - another commit with word 'Update' => SINGLE increment PATCH
|
||||
- 0.1.0 - MINOR - after commit with word 'Change' => increment MINOR, reset PATCH
|
||||
- 0.1.0 - PATCH - additional commit
|
||||
- 1.0.0 - MAJOR - commit with word 'BREAKING' = > INCREMENT MAJOR, reset MINOR
|
||||
- 1.0.0 - PATCH - another commit
|
||||
```
|
||||
|
||||
#### Release candidates
|
||||
|
||||
The `semver-gen` supports release candidates generation as well. Add following configuration ( and change the trigger keywords to anything what suits you )
|
||||
to generate the appropriate release in format `1.3.37-rc.1` and counting up until next `minor` trigger will be detected.
|
||||
|
||||
```yaml
|
||||
release:
|
||||
- release-candidate
|
||||
- add-rc
|
||||
```
|
||||
|
||||
#### Example configuration
|
||||
Create a `semver.yaml` file (or specify a different path with `-c`):
|
||||
|
||||
```yaml
|
||||
version: 1
|
||||
@@ -173,6 +166,8 @@ force:
|
||||
minor: 0
|
||||
patch: 1
|
||||
commit: 69fbe2df696f40281b9104ff073d26186cde1024
|
||||
existing: true
|
||||
strict: false
|
||||
blacklist:
|
||||
- "Merge branch"
|
||||
- "Merge pull request"
|
||||
@@ -182,25 +177,111 @@ wording:
|
||||
patch:
|
||||
- update
|
||||
- initial
|
||||
- fix
|
||||
minor:
|
||||
- change
|
||||
- improve
|
||||
- add
|
||||
major:
|
||||
- breaking
|
||||
- the # For testing purposes
|
||||
- redesign
|
||||
release:
|
||||
- release-candidate
|
||||
- add-rc
|
||||
```
|
||||
|
||||
* `version`: is not respected at the moment, introduced for potential backwards compatibility in future
|
||||
* `force`: sets the "starting" version, you don't need to specify this section as the default is always `0`
|
||||
* `force.commit`: allows you to set commit hash from which the calculations should start
|
||||
* `blacklist`: terms to ignore when processing commits. Any commit containing these terms will be skipped in version calculations. Useful for ignoring merge commits, feature branch names, and other unwanted triggers.
|
||||
* `wording`: words the program should look for in the git commits to increment (patch|minor|major)
|
||||
Configuration options:
|
||||
- `version`: Reserved for future backward compatibility
|
||||
- `force`: Set starting version or other constraints
|
||||
- `blacklist`: Terms to ignore when processing commits
|
||||
- `wording`: Keywords that trigger version increments
|
||||
|
||||
### Good to know
|
||||
### Versioning Behavior
|
||||
|
||||
* Word matching uses fuzzy search AND is case INSENSITIVE
|
||||
* I do not recommend using common words ( like "the" from the example configuration )
|
||||
* You can specify env variable `LOG_LEVEL=debug` to see what exactly happens during the calculations
|
||||
The version calculation follows semantic versioning rules:
|
||||
- **MAJOR**: Incremented for incompatible API changes
|
||||
- **MINOR**: Incremented for backward-compatible new features
|
||||
- **PATCH**: Incremented for backward-compatible bug fixes
|
||||
|
||||
When keywords are matched:
|
||||
- **MAJOR** match: Increments major version, resets minor and patch versions
|
||||
- **MINOR** match: Increments minor version, resets patch version
|
||||
- **PATCH** match: Increments patch version
|
||||
- By default (non-strict mode), every commit increments patch version
|
||||
|
||||
### Release Candidates
|
||||
|
||||
Add the following to your configuration to generate release candidates:
|
||||
|
||||
```yaml
|
||||
wording:
|
||||
release:
|
||||
- release-candidate
|
||||
- add-rc
|
||||
```
|
||||
|
||||
When a release candidate keyword is found, the version will be formatted as `1.2.3-rc.1`, with the counter incrementing for each new release candidate.
|
||||
|
||||
## Examples
|
||||
|
||||
### Standard Mode
|
||||
|
||||
```
|
||||
- 0.0.1 - PATCH - starting commit
|
||||
- 0.0.2 - PATCH - another commit
|
||||
- 0.0.4 - PATCH - another commit with word 'Update' => DOUBLE increment PATCH
|
||||
- 0.1.0 - MINOR - after commit with word 'Change' => increment MINOR, reset PATCH
|
||||
- 0.1.1 - PATCH - additional commit
|
||||
- 1.0.1 - MAJOR - commit with word 'BREAKING' => INCREMENT MAJOR, reset MINOR
|
||||
- 1.0.2 - PATCH - another commit
|
||||
```
|
||||
|
||||
### Strict Matching Mode
|
||||
|
||||
In strict mode (using `-s` flag or `force.strict: true`), versions only increment when a keyword is matched:
|
||||
|
||||
```
|
||||
- 0.0.1 - PATCH - starting commit
|
||||
- 0.0.1 - PATCH - another commit (no change - no keyword match)
|
||||
- 0.0.2 - PATCH - another commit with word 'Update' => increment PATCH
|
||||
- 0.1.0 - MINOR - after commit with word 'Change' => increment MINOR, reset PATCH
|
||||
- 0.1.0 - PATCH - additional commit (no change - no keyword match)
|
||||
- 1.0.0 - MAJOR - commit with word 'BREAKING' => INCREMENT MAJOR, reset MINOR
|
||||
- 1.0.0 - PATCH - another commit (no change - no keyword match)
|
||||
```
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Force Settings
|
||||
|
||||
Control versioning with force settings in configuration:
|
||||
|
||||
```yaml
|
||||
force:
|
||||
major: 1 # Set minimum major version
|
||||
minor: 0 # Set minimum minor version
|
||||
patch: 1 # Set minimum patch version
|
||||
commit: 69fbe2df696f40281b9104ff073d26186cde1024 # Start from specific commit
|
||||
existing: true # Respect existing tags (same as -e flag)
|
||||
strict: false # Use strict matching (same as -s flag)
|
||||
```
|
||||
|
||||
### Blacklist Terms
|
||||
|
||||
Ignore specific commits from version calculations:
|
||||
|
||||
```yaml
|
||||
blacklist:
|
||||
- "Merge branch" # Ignore merge commits
|
||||
- "Merge pull request" # Ignore PR merges
|
||||
- "feature/" # Ignore feature branch names
|
||||
- "chore:" # Ignore chore commits
|
||||
```
|
||||
|
||||
## Tips & Best Practices
|
||||
|
||||
- Word matching uses fuzzy search and is case INSENSITIVE
|
||||
- Avoid common words as version triggers (e.g., "the", "and")
|
||||
- Use `LOG_LEVEL=debug` environment variable to see detailed calculation steps
|
||||
- When using as a GitHub Action, ensure `fetch-depth: '0'` to get the complete commit history
|
||||
- For complex projects, consider using a more specific configuration to distinguish between types of changes
|
||||
|
||||
Reference in New Issue
Block a user