diff --git a/README.md b/README.md index 7adfaa9..0177cb5 100644 --- a/README.md +++ b/README.md @@ -2,15 +2,32 @@ Features: * Conventional Commit linter -* Generate CHANGELOG +* Generate CHANGELOG and group of CHANGELOGs * Bump version based on CHANGELOG -# Examples -You may use it as a Python package or a Docker container. +# DevOps and Tool Developers Section -## PIP Package +## Examples +You may use it as a CLI tool (Python PIP package) or a Docker container. + +### Usage as PIP Package (python is required) + +#### Check commit message + +```shell +$ pygitver --check-commit-message "feat: conventional commit example" +$ echo $? +0 +$ pygitver --check-commit-message "non-conventional commit example" +ERROR: Commit does not fit Conventional Commits requirements +More about Conventional Commits: https://www.conventionalcommits.org/en/v1.0.0/ +$ echo $? +1 +``` + +#### Get current/next version ```shell $ git tag -l v0.0.1 @@ -19,11 +36,62 @@ $ pygitver --curr-ver v0.0.2 $ pygitver --next-ver v0.0.3 - ``` +#### Generate changelog +```shell +$ pygitver changelog +########## +Change Log +########## + +Version v0.0.3 +============= + +Features +-------- + +* Allow to trigger job manually + +Bug Fixes +--------- + +* Path for the default changelog template + +* Readme.md usage + +Improved Documentation +---------------------- + +* Add examples to the readme.md + +$ pygitver changelog --format json | jq . +{ + "version": "v0.0.3", + "bump_rules": { + "major": false, + "minor": false, + "patch": true + }, + "changelog": { + "features": [ + "allow to trigger job manually" + ], + "bugfixes": [ + "path for the default changelog template", + "README.md usage" + ], + "deprecations": [], + "others": [], + "docs": [ + "Add examples to the README.md" + ], + "non_conventional_commit": [] + } +} +``` -## Docker Container +### Usage as Docker container (docker engine is required) ```shell $ git tag -l @@ -103,7 +171,15 @@ Get changelog: Get changelog in TEXT or JSON format ``` -## Conventional Commits Rules +## Custom CHANGELOG Templates + +* Take as an example: `./src/pygitver/templates/changelog.tmpl` +* Place somewhere in your project custom template +* Send environment variable `PYGITVER_TEMPLATE_CHANGELOG` to docker + on run with full template path in Docker (usually `/app/...`) + + +# Conventional Commits Rules The tool supports simplified Conventional Commits, which are described in this section. The commit message should be structured as follows: @@ -117,7 +193,7 @@ The commit contains the following structural elements to communicate intent to t * `BREAKING CHANGE:` a commit that has a footer `BREAKING CHANGE:`, or appends a `!` after the type/scope, introduces a breaking API change (correlating with `MAJOR` in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type. * Other allowed prefixes: `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`. These correlate with `PATCH` in Semantic Versioning. -### Conventional Commits Examples: +## Conventional Commits Examples: Commit without scope without breaking change. ``` @@ -143,10 +219,10 @@ feat(lang): add Polish language ``` -## Users (Developers) Section +# Users (Developers) Section -### Install pygitver +## Install Conventional Commit Git Hook Checker Run in the `git` root folder of the target repository on localhost. ```shell docker run --rm -v $(pwd):/app -w /app --user "$(id -u):$(id -g)" --entrypoint '' panpuchkov/pygitver /pygitver/scripts/install.sh @@ -155,7 +231,7 @@ docker run --rm -v $(pwd):/app -w /app --user "$(id -u):$(id -g)" --entrypoint ' * It doesn't matter what the current branch is. * You should install it in every repository that needs conventional commit messages. -### Update pygitver +## Update pygitver Run in a terminal in any folder: @@ -163,7 +239,7 @@ Run in a terminal in any folder: docker pull panpuchkov/pygitver ``` -### Usage +## Git Conventional Commit Linter You don't need to use it directly; it will be used automatically on each git commit. @@ -182,70 +258,26 @@ $ git commit -am "feat: test" _Note: repeat this procedure for each repository_ -## DevOps and Tool Developers Section - -### Usage - -_**Note:** The tool is running in the docker container and mounting your repository. -It means that you have to run it just from the repository's root directory, -from the directory with `.git` folder._ - -```shell -docker run --rm -v $(pwd):/app -w /app panpuchkov/pygitver --help -``` - -#### Examples - -Check if the git commit message is valid for Conventional Commits: -```shell -$ docker run --rm -v $(pwd):/app -w /app panpuchkov/pygitver --check-commit-message "feat: conventional commit message" -$ echo $? # get exit code -0 -$ docker run --rm -v $(pwd):/app -w /app panpuchkov/pygitver --check-commit-message "non-conventional commit message" -ERROR: Commit does not fit Conventional Commits requirements -$ echo $? # get exit code -1 -``` - -Get current version (last git tag): -```shell -$ docker run --rm -v $(pwd):/app -w /app --user "$(id -u):$(id -g)" panpuchkov/pygitver --curr-ver -v0.0.3 -``` - -Get next version (bump last git tag): -```shell -$ docker run --rm -v $(pwd):/app -w /app --user "$(id -u):$(id -g)" panpuchkov/pygitver --next-ver -v1.0.0 -``` - -#### Custom CHANGELOG Templates - -* Take as an example: `./src/templates/changelog.tmpl` -* Place somewhere in your project custom template -* Send environment variable `PYGITVER_TEMPLATE_CHANGELOG` to docker - on run with full template path in Docker (usually `/app/...`) - -### Development +# Development -#### Build Docker +## Build Docker ```shell docker build -t pygitver . ``` -#### Install to Localhost +## Install to Localhost ```shell pip install -r requirements-dev.txt ``` -#### Test on Localhost +## Test on Localhost -##### Run all checks +### Run all checks ```shell tox ``` -##### A single file of the test run +### A single file of the test run ```shell tox -e coverage -- ./tests/test_git.py -vv ``` @@ -254,11 +286,11 @@ or coverage run -m pytest -- ./tests/test_git.py ``` -#### Build pip package +## Build pip package Linux ```shell -python3 -m build +python -m build ``` For `Debian` based OS: