pub/git-sv
pub/git-sv
1
0
Fork 0
Code Activity

docs: add template and release-notes sections to readme

Browse source 
issue: #40
This commit is contained in:
Beatriz Vieira 2022-02-28 23:43:39 -03:00
parent 7871515ac0
commit 2c741062f7
1 changed files with 115 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

125
README.md
View file

@ -1,6 +1,6 @@
<p align="center">
<h1 align="center">sv4git</h1>
<p align="center">semantic version for git</p>
<p align="center">A command line tool (CLI) to validate commit messages, bump version, create tags and generate changelogs!</p>
<p align="center">
<a href="https://github.com/bvieira/sv4git/releases/latest"><img alt="Release" src="https://img.shields.io/github/release/bvieira/sv4git.svg?style=for-the-badge"></a>
<a href="https://pkg.go.dev/github.com/bvieira/sv4git/v2"><img alt="Go Reference" src="https://img.shields.io/badge/-Reference-blue?style=for-the-badge&logo=go&labelColor=gray"></a>
@ -26,11 +26,17 @@
If you want to install from source using `go install`, just run:
```bash
# keep in mind that with this, it will compile from source and won't show the version on cli -h.
go install github.com/bvieira/sv4git/v2/cmd/git-sv@latest
# if you want to add the version on the binary, run this command instead.
SV4GIT_VERSION=$(go list -f '{{ .Version }}' -m github.com/bvieira/sv4git/v2@latest | sed 's/v//') && go install --ldflags "-X main.Version=$SV4GIT_VERSION" github.com/bvieira/sv4git/v2/cmd/git-sv@v$SV4GIT_VERSION
```
### Config
#### YAML
There are 3 config levels when using sv4git: [default](#default), [user](#user), [repository](#repository). All of them are merged considering the follow priority: **repository > user > default**.
To see the current config, run:
@ -39,9 +45,9 @@ To see the current config, run:
git sv cfg show
```
#### Configuration Types
##### Configuration Types
##### Default
###### Default
To check the default configuration, run:
@ -49,7 +55,7 @@ To check the default configuration, run:
git sv cfg default
```
##### User
###### User
For user config, it is necessary to define the `SV4GIT_HOME` environment variable, eg.:
@ -64,14 +70,14 @@ And create a `config.yml` file inside it, eg.:
└── config.yml
```
##### Repository
###### Repository
Create a `.sv4git.yml` file on the root of your repository, eg.: [.sv4git.yml](.sv4git.yml).
#### Configuration format
##### Configuration format
```yml
version: "1.0" #config version
version: "1.1" #config version
versioning: # versioning bump
update-major: [] # Commit types used to bump major.
@ -85,13 +91,23 @@ tag:
pattern: '%d.%d.%d' # Pattern used to create git tag.
release-notes:
# Headers names for release notes markdown. To disable a section just remove the header line.
# It's possible to add other commit types, the release note will be created respecting the following order:
# feat, fix, refactor, perf, test, build, ci, chore, docs, style, breaking-change
# Deprecated!!! please use 'sections' instead! Headers names for release notes markdown. To disable a section
# just remove the header line. It's possible to add other commit types, the release note will be created
# respecting the following order: feat, fix, refactor, perf, test, build, ci, chore, docs, style, breaking-change.
headers:
breaking-change: Breaking Changes
feat: Features
fix: Bug Fixes
sections: # Array with each section of release note. Check template section for more information.
- name: Features # Name used on section name.
section-type: commits # Type of the section, supported types: commits, breaking-changes.
commit-types: [feat] # Commit types for commit section-type, one commit type cannot be in more than one section.
- name: Bug Fixes
section-type: commits
commit-types: [fix]
- name: Breaking Changes
section-type: breaking-changes
branches: # Git branches config.
prefix: ([a-z]+\/)? # Prefix used on branch name, it should be a regex group.
@ -116,6 +132,95 @@ commit-message:
regex: '[A-Z]+-[0-9]+' # Regex for issue id.
```
#### Templates
**sv4git** 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). On v2.7.0+, its possible to overwrite the default configuration by adding `.sv4git/templates` on your repository. The cli expects that at least 2 files exists on your directory: `changelog-md.tpl` and `releasenotes-md.tpl`.
```bash
.sv4git
└── templates
├── changelog-md.tpl
└── releasenotes-md.tpl
```
Everything inside `.sv4git/templates` will be loaded, so it's possible to add more files to be used as needed.
##### 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.
| section-type | ReleaseNoteSection |
| -- | -- |
| commits | ReleaseNoteCommitsSection |
| breaking-changes | ReleaseNoteBreakingChangeSection |
> 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 // If has a version, it will be used, if not use tag 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 function implementation.
###### timefmt
**Usage:** timefmt time "2006-01-02"
Receive a time.Time and a layout string and returns a textual representation of the time according with the layout provided. Check <https://pkg.go.dev/time#Time.Format> for more information.
###### getsection
**Usage:** getsection sections "Features"
Receive a list of ReleaseNoteSection and a Section name and returns a section with the provided name. If no section is found, it will return `nil`.
### Running
Run `git-sv` to get the list of available parameters: