type: BodyConfig | optional
Options to customize the body prompt
type: string
| optional | template type: Change
Template used to generate change lines in version files and changelog. Custom values are created through custom choices and can be accessible through the Custom argument.
changeFormat: '* [#{{.Custom.Issue}}](https://github.com/miniscruff/changie/issues/{{.Custom.Issue}}) {{.Body}}'
type: string
| optional
Filepath for the generated changelog file. Relative to project root. ChangelogPath is not required if you are using projects.
changelogPath: CHANGELOG.md
type: string
| required
Directory for change files, header file and unreleased files. Relative to project root.
changesDir: .changes
type: string
| optional | template type: ComponentData
Template used to generate component headers. If format is empty no header will be included. If components are disabled, the format is unused.
type: []string
| optional
Components are an additional layer of organization suited for projects that want to split change fragments by an area or tag of the project. An example could be splitting your changelogs by packages for a monorepo. If no components are listed then the component prompt will be skipped and no component header included. By default no components are configured.
components:
- API
- CLI
- Frontend
type: []Custom | optional
Custom choices allow you to ask for additional information when creating a new change fragment. These custom choices are included in the change custom value.
# github issue and author name
custom:
- key: Issue
type: int
minInt: 1
- key: Author
label: GitHub Name
type: string
minLength: 3
type: string
| optional
Prefix of environment variables to load for templates. The prefix is removed from resulting key map.
# if we have an environment variable like so:
# export CHANGIE_PROJECT=changie
# we can use that in our templates if we set the prefix
envPrefix: "CHANGIE_"
versionFormat: "New release for {{.Env.PROJECT}}"
type: string
| optional | template type: BatchData
Template used to generate a version footer.
# config yaml
custom:
- key: Author
type: string
minLength: 3
footerFormat: |
### Contributors
{{- range (customs .Changes "Author" | uniq) }}
* [{{.}}](https://github.com/{{.}})
{{- end}}
type: string
| optional | template type: Change
Customize the file name generated for new fragments. The default uses the component and kind only if configured for your project. The file is placed in the unreleased directory, so the full path is:
“{{.ChangesDir}}/{{.UnreleasedDir}}/{{.FragmentFileFormat}}.yaml”
fragmentFileFormat: "{{.Kind}}-{{.Custom.Issue}}"
type: string
| optional | template type: BatchData
Template used to generate a version header.
type: string
| optional
Header content included at the top of the merged changelog. A default header file is created when initializing that follows “Keep a Changelog”.
Filepath for your changelog header file. Relative to changesDir.
headerPath: header.tpl.md
type: string
| optional | template type: KindData
Template used to generate kind headers. If format is empty no header will be included. If kinds are disabled, the format is unused.
type: []KindConfig | optional
Kinds are another optional layer of changelogs suited for specifying what type of change we are making. If configured, developers will be prompted to select a kind.
The default list comes from keep a changelog and includes; added, changed, removed, deprecated, fixed, and security.
kinds:
- label: Added
- label: Changed
- label: Deprecated
- label: Removed
- label: Fixed
- label: Security
type: NewlinesConfig | optional
Newline options allow you to add extra lines between elements written by changie.
type: []PostProcessConfig | optional
Post process options when saving a new change fragment.
# build a GitHub link from author choice
post:
- key: AuthorLink
value: "https://github.com/{{.Custom.Author}}
changeFormat: "* {{.Body}} by [{{.Custom.Author}}]({{.Custom.AuthorLink}})"
type: []ProjectConfig | optional
Projects allow you to specify child projects as part of a monorepo setup.
projects:
- label: UI
key: ui
changelog: ui/CHANGELOG.md
- label: Email Sender
key: email_sender
changelog: services/email/CHANGELOG.md
type: string
| optional
ProjectsVersionSeparator is used to determine the final version when using projects. The result is: project key + projectVersionSeparator + latest/next version.
projectsVersionSeparator: "_"
type: []Replacement | optional
Replacements to run when merging a changelog.
# nodejs package.json replacement
replacements:
- path: package.json
find: ' "version": ".*",'
replace: ' "version": "{{.VersionNoPrefix}}",'
type: string
| required
Directory for all unreleased change files. Relative to changesDir.
unreleasedDir: unreleased
type: string
| required
File extension for generated version files. This should probably match your changelog path file. Must not include the period.
# for markdown changelogs
versionExt: md
type: string
| optional
Filepath for your version footer file relative to unreleasedDir. It is also possible to use the ‘–footer-path’ parameter when using the batch command.
type: string
| optional | template type: BatchData
Template used to generate version headers.
type: string
| optional
Filepath for your version header file relative to unreleasedDir. It is also possible to use the ‘–header-path’ parameter when using the batch command.
Batch data is a common structure for templates when generating change fragments.
type: []Change | optional
Changes included in the batch
type: map [ string
] string
| optional
Env vars configured by the system. See envPrefix for configuration.
type: int
| optional
Major value of the version
type: string
| optional
Metadata value of the version
type: int
| optional
Minor value of the version
type: int
| optional
Patch value of the version
type: string
| optional
Prerelease value of the version
type: string
| optional
Previous released version
type: Time
| optional
Time of the change
type: string
| optional
Version of the change, will include “v” prefix if used
Body config allows you to customize the default body prompt
type: int64
| optional
Max length specifies the maximum body length
type: int64
| optional
Min length specifies the minimum body length
type: bool
| optional
Block allows multiline text inputs for body messages
Change represents an atomic change to a project.
type: string
| optional
Body message of our change, if one was provided.
type: string
| optional
Component of our change, if one was provided.
type: map [ string
] string
| optional
Custom values corresponding to our options where each key-value pair is the key of the custom option and value the one provided in the change.
custom:
- key: Issue
type: int
changeFormat: "{{.Body}} from #{{.Custom.Issue}}"
type: map [ string
] string
| optional
Env vars configured by the system.
This is not written in change fragments but instead loaded by the system and accessible for templates.
For example if you want to use an env var in change format you can,
but env vars configured when executing changie new
will not be saved.
See envPrefix for configuration.
type: string
| optional
Filename the change was saved to.
type: string
| optional
Kind of our change, if one was provided.
type: string
| optional
Project of our change, if one was provided.
type: Time
| required
When our change was made.
Component data stores data related to writing component headers.
type: string
| required
Name of the component
type: map [ string
] string
| optional
Env vars configured by the system. See envPrefix for configuration.
Custom defines a custom choice that is asked when using ‘changie new’. The result is an additional custom value in the change file for including in the change line.
A simple one could be the issue number or authors github name.
- key: Author
label: GitHub Name
type: string
minLength: 3
type: []string
| optional
When using the enum type, you must also specify what possible options to allow. Users will be given a selection list to select the value they want.
type: string
| required
Value used as the key in the custom map for the change format. This should only contain alpha numeric characters, usually starting with a capital.
key: Issue
type: string
| optional
Description used in the prompt when asking for the choice. If empty key is used instead.
label: GitHub Username
type: int64
| optional
If specified the input value must be less than or equal to maxInt.
type: int64
| optional
If specified string input must be no more than this long
type: int64
| optional
If specified the input value must be greater than or equal to minInt.
type: int64
| optional
If specified the string input must be at least this long
type: bool
| optional
If true, an empty value will not fail validation. The optional check is handled before min so you can specify that the value is optional but if it is used it must have a minimum length or value depending on type.
When building templates that allow for optional values you can compare the custom choice to an empty string to check for a value or empty.
custom:
- key: TicketNumber
type: int
optional: true
changeFormat: >-
{{- if not (eq .Custom.TicketNumber "")}}
PROJ-{{.Custom.TicketNumber}}
{{- end}}
{{.Body}}
type: CustomType | required
Specifies the type of choice which changes the prompt.
value | description | options |
---|---|---|
string | Freeform text | minLength and maxLength |
block | Multiline text | minLength and maxLength |
int | Whole numbers | minInt and maxInt |
enum | Limited set of strings | enumOptions is used to specify values |
CustomType determines the possible custom choice types.
Current values are: string
, block
, int
and enum
.
Kind config allows you to customize the options depending on what kind was selected.
type: []Custom | optional
Additional choices allows adding choices per kind
type: string
| optional
Auto determines what value to bump when using batch auto
or next auto
.
Possible values are major, minor or patch and the highest one is used if
multiple changes are found.
auto: minor
type: string
| optional
Change format will override the root change format when building changes specific to this kind.
changeFormat: 'Breaking: {{.Custom.Body}}
type: string
| optional
Format will override the root kind format when building the kind header.
format: '### {{.Kind}} **Breaking Changes**'
type: string
| required
Label is the value used in the prompt when selecting a kind.
label: Feature
type: []PostProcessConfig | optional
Post process options when saving a new change fragment specific to this kind.
type: bool
| optional
Skip body allows skipping the parent body prompt.
type: bool
| optional
Skip global choices allows skipping the parent choices options.
type: bool
| optional
Skip global post allows skipping the parent post processing.
Kind data stores data related to writing kind headers.
type: map [ string
] string
| optional
Env vars configured by the system. See envPrefix for configuration.
type: string
| required
Name of the kind
Configuration options for newlines before and after different elements.
type: int
| optional
Add newlines after change fragment
type: int
| optional
Add newlines after the header file in the merged changelog
type: int
| optional
Add newlines after adding a version to the changelog
type: int
| optional
Add newlines after component
type: int
| optional
Add newlines after footer file
type: int
| optional
Add newlines after footer template
type: int
| optional
Add newlines after header file
type: int
| optional
Add newlines after header template
type: int
| optional
Add newlines after kind
type: int
| optional
Add newlines after version
type: int
| optional
Add newlines before change fragment
type: int
| optional
Add newlines before adding a version to the changelog
type: int
| optional
Add newlines before component
type: int
| optional
Add newlines before footer file
type: int
| optional
Add newlines before footer template
type: int
| optional
Add newlines before header file
type: int
| optional
Add newlines before header template
type: int
| optional
Add newlines before kind
type: int
| optional
Add newlines before version
type: int
| optional
Add newlines at the end of the version file
PostProcessConfig allows adding additional custom values to a change fragment
after all the other inputs are complete.
This will add additional keys to the custom
section of the fragment.
If the key already exists as part of a custom choice the value will be overridden.
type: string
| optional
Key to save the custom value with
type: string
| optional | template type: Change
Value of the custom value as a go template
ProjectConfig extends changie to support multiple changelog files for different projects inside one repository.
projects:
- label: UI
key: ui
changelog: ui/CHANGELOG.md
- label: Email Sender
key: email_sender
changelog: services/email/CHANGELOG.md
type: string
| optional
ChangelogPath is the path to the changelog for this project.
changelog: src/frontend/CHANGELOG.md
type: string
| optional
Key is the value used for unreleased and version output paths.
key: frontend
type: string
| optional
Label is the value used in the prompt when selecting a project.
label: Frontend
Template data used for replacing version values.
type: int
| optional
Major value of the version
type: string
| optional
Metadata value of the version
type: int
| optional
Minor value of the version
type: int
| optional
Patch value of the version
type: string
| optional
Prerelease value of the version
type: string
| optional
Version of the release, will include “v” prefix if used
type: string
| optional
Version of the release without the “v” prefix if used
Replacement handles the finding and replacing values when merging the changelog. This can be used to keep version strings in-sync when preparing a release without having to manually update them. This works similar to the find and replace from IDE tools but also includes the file path of the file.
# NodeJS package.json
replacements:
- path: package.json
find: ' "version": ".*",'
replace: ' "version": "{{.VersionNoPrefix}}",'
type: string
| required
Regular expression to search for in the file.
type: string
| optional
Optional regular expression mode flags. Defaults to the m flag for multiline such that ^ and $ will match the start and end of each line and not just the start and end of the string.
For more details on regular expression flags in Go view the regexp/syntax.
type: string
| required
Path of the file to find and replace in.
type: string
| required | template type: ReplaceData
Template string to replace the line with.
Template cache handles running all the templates for change fragments. Included options include the default go template and sprig functions for formatting. Additionally, custom template functions are listed below for working with changes.
format: |
### Contributors
{{- range (customs .Changes "Author" | uniq) }}
* [{{.}}](https://github.com/{{.}})
{{- end}}
Bodies will return all the bodies from the provided changes.
format: "{{ bodies .Changes }} bodies"
Components will return all the components from the provided changes.
format: "{{components .Changes }} components"
Count will return the number of occurrences of a string in a slice.
format: "{{ kinds .Changes | count \"added\" }} kinds"
Customs will return all the values from the custom map by a key. If a key is missing from a change, it will be an empty string.
format: "{{ customs .Changes \"Author\" }} authors"
Kinds will return all the kindsi from the provided changes.
format: "{{ kinds .Changes }} kinds"
Times will return all the times from the provided changes.
format: "{{ times .Changes }} times"