From 0d2a36112b7133c41860e2d3c3c7e75d8145b95e Mon Sep 17 00:00:00 2001 From: Robert Kaussow Date: Thu, 12 Oct 2023 17:26:56 +0200 Subject: [PATCH] cleanup docs and repo settings --- .dictionary | 13 +++ .github/settings.yml | 5 +- .woodpecker/docs.yml | 2 +- CONTRIBUTING.md | 31 ++++++ README.md | 225 ++++++++++++------------------------------- cmd/git-sv/main.go | 4 +- 6 files changed, 108 insertions(+), 172 deletions(-) create mode 100644 .dictionary create mode 100644 CONTRIBUTING.md diff --git a/.dictionary b/.dictionary new file mode 100644 index 0000000..48a8d97 --- /dev/null +++ b/.dictionary @@ -0,0 +1,13 @@ +git-sv +YAML +.gitsv +cli +getsection +timefmt +cfg +json +changelog +ReleaseNoteSection +ReleaseNoteCommitsSection +ReleaseNoteBreakingChangeSection +ReleaseNoteSection diff --git a/.github/settings.yml b/.github/settings.yml index 1dae6d2..060e33c 100644 --- a/.github/settings.yml +++ b/.github/settings.yml @@ -1,8 +1,7 @@ repository: name: git-sv - description: Woodpecker CI plugin to perform git actions - homepage: https://woodpecker-plugins.geekdocs.de/plugins/git-sv - topics: woodpecker-ci, woodpecker, woodpecker-plugin + description: Semantic versioning tool for git based on conventional commits + topics: cli, tools, git private: false has_issues: true diff --git a/.woodpecker/docs.yml b/.woodpecker/docs.yml index 8d8b85c..5da3c3e 100644 --- a/.woodpecker/docs.yml +++ b/.woodpecker/docs.yml @@ -45,7 +45,7 @@ steps: target: DOCKER_USER environment: PUSHRM_FILE: README.md - PUSHRM_SHORT: Woodpecker CI plugin to perform git actions + PUSHRM_SHORT: Semantic versioning tool for git based on conventional commits PUSHRM_TARGET: ${CI_REPO} when: - event: [push, manual] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..72264c4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,31 @@ +# Contributing + +## Security + +If you think you have found a **security issue**, please do not mention it in this repository. +Instead, send an email to `security@thegeeklab.de` with as many details as possible so it can be handled confidential. + +## Bug Reports and Feature Requests + +If you have found a **bug** or have a **feature request** please use the search first in case a similar issue already exists. +If not, please create an issue in this repository + +## Code + +If you would like to fix a bug or implement a feature, please fork the repository and create a Pull Request. + +Before you start any Pull Request, it is recommended that you create an issue to discuss first if you have any +doubts about requirement or implementation. That way you can be sure that the maintainer(s) agree on what to change and how, +and you can hopefully get a quick merge afterwards. + +Pull Requests can only be merged once all status checks are green. + +## Do not force push to your Pull Request branch + +Please do not force push to your Pull Requests branch after you have created your Pull Request, as doing so makes it harder for us to review your work. +Pull Requests will always be squashed by us when we merge your work. Commit as many times as you need in your Pull Request branch. + +## Re-requesting a review + +Please do not ping your reviewer(s) by mentioning them in a new comment. Instead, use the re-request review functionality. +Read more about this in the [GitHub docs, Re-requesting a review](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/incorporating-feedback-in-your-pull-request#re-requesting-a-review). diff --git a/README.md b/README.md index b5e4563..4981101 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,26 @@ # git-sv -A command line tool (CLI) to validate commit messages, bump version, create tags and generate changelogs. +Semantic versioning tool for git based on conventional commits. + +[![Build Status](https://ci.thegeeklab.de/api/badges/thegeeklab/git-sv/status.svg)](https://ci.thegeeklab.de/repos/thegeeklab/git-sv) +[![Go Report Card](https://goreportcard.com/badge/github.com/thegeeklab/git-sv)](https://goreportcard.com/report/github.com/thegeeklab/git-sv) +[![GitHub contributors](https://img.shields.io/github/contributors/thegeeklab/git-sv)](https://github.com/thegeeklab/git-sv/graphs/contributors) +[![License: MIT](https://img.shields.io/github/license/thegeeklab/git-sv)](https://github.com/thegeeklab/git-sv/blob/main/LICENSE) ## Getting Started -### Pre Requirements +### Requirements - Git 2.17+ ### Installing - Download the latest release and add the binary to your path. -- Optional: Set `GITSV_HOME` to define user configs. Check the [Config](#config) topic for more information. +- Optional: Set `GITSV_HOME` to define user configurations. Check the [Configuration](#configuration) topic for more information. If you want to install from source using `go install`, just run: -```bash +```Shell # keep in mind that with this, it will compile from source and won't show the version on cli -h. go install github.com/thegeeklab/git-sv/v2/cmd/git-sv@latest @@ -23,15 +28,15 @@ go install github.com/thegeeklab/git-sv/v2/cmd/git-sv@latest GITSV_VERSION=$(go list -f '{{ .Version }}' -m github.com/thegeeklab/git-sv/v2@latest | sed 's/v//') && go install --ldflags "-X main.Version=$SGITSV_VERSION" github.com/thegeeklab/git-sv/v2/cmd/git-sv@v$GITSV_VERSION ``` -### Config +### Configuration #### YAML -There are 3 config levels when using git-sv: [default](#default), [user](#user), [repository](#repository). All of them are merged considering the follow priority: **repository > user > default**. +There are 3 configuration levels when using git-sv: [default](#default), [user](#user), [repository](#repository). All of them are merged considering the follow priority: **repository > user > default**. -To see the current config, run: +To see the current configuration, run: -```bash +```Shell git sv cfg show ``` @@ -41,33 +46,33 @@ git sv cfg show To check the default configuration, run: -```bash +```Shell git sv cfg default ``` ###### User -For user config, it is necessary to define the `GITSV_HOME` environment variable, eg.: +For user configuration, it is necessary to define the `GITSV_HOME` environment variable, e.g.: -```bash +```Shell GITSV_HOME=/home/myuser/.gitsv # myuser is just an example. ``` -And create a `config.yml` file inside it, eg.: +And create a `config.yml` file inside it, e.g.: -```bash +```Shell .gitsv └── config.yml ``` ###### Repository -Create a `.gitsv/config.yml` file on the root of your repository, eg. [.gitsv/config.yml](.gitsv/config.yml). +Create a `.gitsv/config.yml` file on the root of your repository, e.g. [.gitsv/config.yml](.gitsv/config.yml). ##### Configuration format -```yml -version: "1.1" #config version +```Yaml +version: "1.1" #configuration version versioning: # versioning bump update-major: [] # Commit types used to bump major. @@ -141,7 +146,7 @@ commit-message: **git-sv** uses _go templates_ to format the output for `release-notes` and `changelog`, to see how the default template is configured check [template directory](cmd/git-sv/resources/templates). It's possible to overwrite the default configuration by adding `.gitsv/templates` on your repository. The cli expects that at least 2 files exists on your directory: `changelog-md.tpl` and `releasenotes-md.tpl`. -```bash +```Shell .gitsv └── templates ├── changelog-md.tpl @@ -152,9 +157,9 @@ Everything inside `.gitsv/templates` will be loaded, so it's possible to add mor ##### Variables -To execute the template the `releasenotes-md.tpl` will receive a single **ReleaseNote** and `changelog-md.tpl` will receive a list of **ReleaseNote** as variables. +To execute the template the `releasenotes-md.tpl` will receive a single `ReleaseNote` and `changelog-md.tpl` will receive a list of `ReleaseNote` as variables. -Each **ReleaseNoteSection** will be configured according with `release-notes.section` from config file. The order for each section will be maintained and the **SectionType** is defined according with `section-type` attribute as described on the table below. +Each `ReleaseNoteSection` will be configured according with `release-notes.section` from configuration file. The order for each section will be maintained and the `SectionType` is defined according with `section-type` attribute as described on the table below. | section-type | ReleaseNoteSection | | ---------------- | -------------------------------- | @@ -163,56 +168,9 @@ Each **ReleaseNoteSection** will be configured according with `release-notes.sec > :warning: currently only `commits` and `breaking-changes` are supported as `section-types`, using a different value for this field will make the section to be removed from the template variables. -Check below the variables available: - -```go -ReleaseNote - Release string // 'v' followed by version if present, if not tag will be used instead. - Tag string // Current tag, if available. - Version *Version // Version from tag or next version according with semver. - Date time.Time - Sections []ReleaseNoteSection // ReleaseNoteCommitsSection or ReleaseNoteBreakingChangeSection - AuthorNames []string // Author names recovered from commit message (user.name from git) - -Version - Major int - Minor int - Patch int - Prerelease string - Metadata string - Original string - -ReleaseNoteCommitsSection // SectionType == commits - SectionType string - SectionName string - Types []string - Items []GitCommitLog - HasMultipleTypes bool - -ReleaseNoteBreakingChangeSection // SectionType == breaking-changes - SectionType string - SectionName string - Messages []string - -GitCommitLog - Date string - Timestamp int - AuthorName string - Hash string - Message CommitMessage - -CommitMessage - Type string - Scope string - Description string - Body string - IsBreakingChange bool - Metadata map[string]string -``` - ##### Functions -Beside the [go template functions](https://pkg.go.dev/text/template#hdr-Functions), the folowing functions are availiable to use in the templates. Check [formatter_functions.go](sv/formatter_functions.go) to see the functions implementation. +Beside the [go template functions](https://pkg.go.dev/text/template#hdr-Functions), the following functions are available to use in the templates. Check [formatter_functions.go](sv/formatter_functions.go) to see the functions implementation. ###### timefmt @@ -230,7 +188,7 @@ Receive a list of ReleaseNoteSection and a Section name and returns a section wi Run `git-sv` to get the list of available parameters: -```bash +```Shell git-sv ``` @@ -238,7 +196,7 @@ git-sv If `git-sv` is configured on your path, you can use it like a git command: -```bash +```Shell git sv git sv current-version git sv next-version @@ -248,43 +206,48 @@ git sv next-version Use `--help` or `-h` to get usage information, don't forget that some commands have unique options too: -```bash -# sv help -git-sv -h +```Shell +$ git-sv --help +NAME: + git-sv - Semantic version for git. -# sv release-notes command help -git-sv rn -h +USAGE: + git-sv [global options] command [command options] [arguments...] + +VERSION: + 20e64f8 + +COMMANDS: + config, cfg cli configuration + current-version, cv get last released version from git + next-version, nv generate the next version based on git commit messages + commit-log, cl list all commit logs according to range as jsons + commit-notes, cn generate a commit notes according to range + release-notes, rn generate release notes + changelog, cgl generate changelog + tag, tg generate tag with version based on git commit messages + commit, cmt execute git commit with convetional commit message helper + validate-commit-message, vcm use as prepare-commit-message hook to validate and enhance commit message + help, h Shows a list of commands or help for one command + +GLOBAL OPTIONS: + --help, -h show help + --version, -v print the version ``` -##### Available commands - -| Variable | description | has options or subcommands | -| ---------------------------- | -------------------------------------------------------------- | :------------------------: | -| config, cfg | Show config information. | :heavy_check_mark: | -| current-version, cv | Get last released version from git. | :x: | -| next-version, nv | Generate the next version based on git commit messages. | :x: | -| commit-log, cl | List all commit logs according to range as jsons. | :heavy_check_mark: | -| commit-notes, cn | Generate a commit notes according to range. | :heavy_check_mark: | -| release-notes, rn | Generate release notes. | :heavy_check_mark: | -| changelog, cgl | Generate changelog. | :heavy_check_mark: | -| tag, tg | Generate tag with version based on git commit messages. | :x: | -| commit, cmt | Execute git commit with convetional commit message helper. | :heavy_check_mark: | -| validate-commit-message, vcm | Use as prepare-commit-message hook to validate commit message. | :heavy_check_mark: | -| help, h | Shows a list of commands or help for one command. | :x: | - ##### Use range Commands like `commit-log` and `commit-notes` has a range option. Supported range types are: `tag`, `date` and `hash`. By default, it's used [--date=short](https://git-scm.com/docs/git-log#Documentation/git-log.txt---dateltformatgt) at `git log`, all dates returned from it will be in `YYYY-MM-DD` format. -Range `tag` will use `git for-each-ref refs/tags` to get the last tag available if `start` is empty, the others types won't use the existing tags. It's recommended to always use a start limit in a old repository with a lot of commits. This behavior was maintained to not break the retrocompatibility. +Range `tag` will use `git for-each-ref refs/tags` to get the last tag available if `start` is empty, the others types won't use the existing tags. It's recommended to always use a start limit in an old repository with a lot of commits. Range `date` use git log `--since` and `--until`. It's possible to use all supported formats from [git log](https://git-scm.com/docs/git-log#Documentation/git-log.txt---sinceltdategt). If `end` is in `YYYY-MM-DD` format, `sv` will add a day on git log command to make the end date inclusive. Range `tag` and `hash` are used on git log [revision range](https://git-scm.com/docs/git-log#Documentation/git-log.txt-ltrevisionrangegt). If `end` is empty, `HEAD` will be used instead. -```bash +```Shell # get commit log as json using a inclusive range git-sv commit-log --range hash --start 7ea9306~1 --end c444318 @@ -292,80 +255,10 @@ git-sv commit-log --range hash --start 7ea9306~1 --end c444318 git-sv commit-log --range tag ``` -##### Use validate-commit-message as prepare-commit-msg hook +## Contributors -Configure your `.git/hooks/prepare-commit-msg`: +Special thanks to all [contributors](https://github.com/thegeeklab/git-sv/graphs/contributors). If you would like to contribute, please see the [instructions](https://github.com/thegeeklab/git-sv/blob/main/CONTRIBUTING.md). -```bash -#!/bin/sh +## License -COMMIT_MSG_FILE=$1 -COMMIT_SOURCE=$2 -SHA1=$3 - -git sv vcm --path "$(pwd)" --file "$COMMIT_MSG_FILE" --source "$COMMIT_SOURCE" -``` - -**Tip**: you can configure a directory as your global git templates using the command below: - -```bash -git config --global init.templatedir '' -``` - -Check [git config docs](https://git-scm.com/docs/git-config#Documentation/git-config.txt-inittemplateDir) for more information! - -## Development - -### Makefile - -Run `make` to get the list of available actions: - -```bash -make -``` - -#### Make configs - -| Variable | description | -| ---------- | ----------------------- | -| BUILDOS | Build OS. | -| BUILDARCH | Build arch. | -| ECHOFLAGS | Flags used on echo. | -| BUILDENVS | Var envs used on build. | -| BUILDFLAGS | Flags used on build. | - -| Parameters | description | -| ---------- | ------------------------------------ | -| args | Parameters that will be used on run. | - -```bash -#variables -BUILDOS="linux" BUILDARCH="amd64" make build - -#parameters -make run args="-h" -``` - -### Build - -```bash -make build -``` - -The binary will be created on `bin/$BUILDOS_$BUILDARCH/git-sv`. - -### Tests - -```bash -make test -``` - -### Run - -```bash -#without args -make run - -#with args -make run args="-h" -``` +This project is licensed under the MIT License - see the [LICENSE](https://github.com/thegeeklab/git-sv/blob/main/LICENSE) file for details. diff --git a/cmd/git-sv/main.go b/cmd/git-sv/main.go index 00af40d..df2fecf 100644 --- a/cmd/git-sv/main.go +++ b/cmd/git-sv/main.go @@ -92,7 +92,7 @@ func main() { { Name: "commit-log", Aliases: []string{"cl"}, - Usage: "list all commit logs according to range as jsons", + Usage: "list all commit logs according to range as json", Description: `The range filter is used based on git log filters, check https://git-scm.com/docs/git-log for more info. When flag range is "tag" and start is empty, last tag created will be used instead. When flag range is "date", if "end" is YYYY-MM-DD the range will be inclusive.`, @@ -132,7 +132,7 @@ When flag range is "date", if "end" is YYYY-MM-DD the range will be inclusive.`, { Name: "commit", Aliases: []string{"cmt"}, - Usage: "execute git commit with convetional commit message helper", + Usage: "execute git commit with conventional commit message helper", Action: commitHandler(cfg, git, messageProcessor), Flags: commitFlags(), },