From a7b929a403ef8d1ad4dc5379f35df9c89f9c6638 Mon Sep 17 00:00:00 2001 From: Carlos A Becker Date: Sat, 6 Nov 2021 16:44:59 -0300 Subject: [PATCH] docs: improve templates.md --- www/docs/customization/templates.md | 46 ++++++++++++++++------------- www/mkdocs.yml | 1 + 2 files changed, 27 insertions(+), 20 deletions(-) diff --git a/www/docs/customization/templates.md b/www/docs/customization/templates.md index d095a4858..b7a10dbc8 100644 --- a/www/docs/customization/templates.md +++ b/www/docs/customization/templates.md @@ -11,7 +11,7 @@ On fields that support templating, these fields are always available: | Key | Description | |---------------------|--------------------------------------------------------------------------------------------------------| | `.ProjectName` | the project name | -| `.Version` | the version being released (`v` prefix stripped) - might be changed in `snapshot` and `nightly` builds | +| `.Version` | the version being released[^1] | | `.Branch` | the current git branch | | `.PrefixedTag` | the current git tag prefixed with the monorepo config tag prefix (if any) | | `.Tag` | the current git tag | @@ -21,11 +21,11 @@ On fields that support templating, these fields are always available: | `.CommitDate` | the UTC commit date in RFC 3339 format | | `.CommitTimestamp` | the UTC commit date in Unix format | | `.GitURL` | the git remote url | -| `.Major` | the major part of the version (assuming `Tag` is a valid semver, else `0`) | -| `.Minor` | the minor part of the version (assuming `Tag` is a valid semver, else `0`) | -| `.Patch` | the patch part of the version (assuming `Tag` is a valid semver, else `0`) | -| `.Prerelease` | the prerelease part of the version, e.g. `beta` (assuming `Tag` is a valid semver) | -| `.RawVersion` | Major.Minor.Patch (assuming `Tag` is a valid semver, else `0.0.0`) | +| `.Major` | the major part of the version[^2] | +| `.Minor` | the minor part of the version[^2] | +| `.Patch` | the patch part of the version[^2] | +| `.Prerelease` | the prerelease part of the version, e.g. `beta`[^2] | +| `.RawVersion` | composed of `{Major}.{Minor}.{Patch}` [^2] | | `.ReleaseNotes` | the generated release notes, available after the changelog step has been executed | | `.IsSnapshot` | `true` if `--snapshot` is set, `false` otherwise | | `.IsNightly` | `true` if `--nightly` is set, `false` otherwise | @@ -33,30 +33,36 @@ On fields that support templating, these fields are always available: | `.Date` | current UTC date in RFC 3339 format | | `.Timestamp` | current UTC time in Unix format | | `.ModulePath` | the go module path, as reported by `go list -m` | -| `incpatch "v1.2.4"` | increments the patch of the given version; will panic if not a semantic version | -| `incminor "v1.2.4"` | increments the minor of the given version; will panic if not a semantic version | -| `incmajor "v1.2.4"` | increments the major of the given version; will panic if not a semantic version | +| `incpatch "v1.2.4"` | increments the patch of the given version[^3] | +| `incminor "v1.2.4"` | increments the minor of the given version[^3] | +| `incmajor "v1.2.4"` | increments the major of the given version[^3] | + +[^1]: The `v` prefix is stripped and it might be changed in `snapshot` and `nightly` builds. +[^2]: Assuming `Tag` is a valid a SemVer, otherwise empty/zeroed. +[^3]: Will panic if not a semantic version. On fields that are related to a single artifact (e.g., the binary name), you may have some extra fields: | Key | Description | |-----------------|---------------------------------------| -| `.Os` | `GOOS` (usually allow replacements) | -| `.Arch` | `GOARCH` (usually allow replacements) | -| `.Arm` | `GOARM` (usually allow replacements) | -| `.Mips` | `GOMIPS` (usually allow replacements) | -| `.Binary` | Binary name | -| `.ArtifactName` | Archive name | -| `.ArtifactPath` | Absolute path to artifact | +| `.Os` | `GOOS`[^4] | +| `.Arch` | `GOARCH`[^4] | +| `.Arm` | `GOARM`[^4] | +| `.Mips` | `GOMIPS`[^4] | +| `.Binary` | binary name | +| `.ArtifactName` | archive name | +| `.ArtifactPath` | absolute path to artifact | + +[^4]: Might have been replaced by `archives.replacements`. On the NFPM name template field, you can use those extra fields as well: | Key | Description | |----------------|------------------------------------------------------------| -| `.Release` | Release from the nfpm config | -| `.Epoch` | Epoch from the nfpm config | -| `.PackageName` | Package the name. Same as `ProjectName` if not overridden. | +| `.Release` | release from the nfpm config | +| `.Epoch` | epoch from the nfpm config | +| `.PackageName` | package the name. Same as `ProjectName` if not overridden. | On all fields, you have these available functions: @@ -68,7 +74,7 @@ On all fields, you have these available functions: | `toupper "v1.2"` | makes input string uppercase. See [ToUpper](https://golang.org/pkg/strings/#ToUpper) | | `trim " v1.2 "` | removes all leading and trailing white space. See [TrimSpace](https://golang.org/pkg/strings/#TrimSpace) | | `trimprefix "v1.2" "v"` | removes provided leading prefix string, if present. See [TrimPrefix](https://golang.org/pkg/strings/#TrimPrefix) | -| `trimsuffix "1.2v" "v"` | removes provided trailing suffix string, if present. See [TrimSuffix](https://pkg.go.dev/strings#TrimSuffix) | +| `trimsuffix "1.2v" "v"` | removes provided trailing suffix string, if present. See [TrimSuffix](https://pkg.go.dev/strings#TrimSuffix) | | `dir .Path` | returns all but the last element of path, typically the path's directory. See [Dir](https://golang.org/pkg/path/filepath/#Dir) | | `abs .ArtifactPath` | returns an absolute representation of path. See [Abs](https://golang.org/pkg/path/filepath/#Abs) | diff --git a/www/mkdocs.yml b/www/mkdocs.yml index e6cd10d41..3dd827ecb 100644 --- a/www/mkdocs.yml +++ b/www/mkdocs.yml @@ -155,3 +155,4 @@ markdown_extensions: - pymdownx.superfences - pymdownx.tasklist: custom_checkbox: true + - footnotes