docs: add template and release-notes sections to readme

issue: #40
2024-11-13 21:30:40 +00:00 · 2022-02-28 23:43:39 -03:00 · 2022-02-28 23:43:39 -03:00 · 2c741062f7
commit 2c741062f7
parent 7871515ac0
1 changed files with 115 additions and 10 deletions
--- a/README.md
+++ b/README.md
@ -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,14 +91,24 @@ 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.
    suffix: (-.*)? # Suffix 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: