54b6cb9afe
* Add more documentation on changelogs Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com> * Add description of modes
57 lines
2.5 KiB
Markdown
57 lines
2.5 KiB
Markdown
# changelog
|
||
|
||
This folder holds changelog updates from commit 3bc7d15 onwards.
|
||
|
||
Release notes are text files with three lines:
|
||
|
||
1. An opening code block with the `release-note:<MODE>` type annotation.
|
||
|
||
For example:
|
||
|
||
```release-note:bug
|
||
|
||
Valid modes are:
|
||
|
||
- `bug` - Any sort of non-security defect fix.
|
||
- `change` - A change in the product that may require action or
|
||
review by the operator. Examples would be any kind of API change
|
||
(as opposed to backwards compatible addition), a notable behavior
|
||
change, or anything that might require attention before updating. Go
|
||
version changes are also listed here since they can potentially have
|
||
large, sometimes unknown impacts. (Go updates are a special case, and
|
||
dep updates in general aren't a `change`). Discussion of any potential
|
||
`change` items in the pull request to see what other communication
|
||
might be warranted.
|
||
- `deprecation` - Announcement of a planned future removal of a
|
||
feature. Only use this if a deprecation notice also exists [in the
|
||
docs](https://www.vaultproject.io/docs/deprecation).
|
||
- `feature` - Large topical additions for a major release. These are
|
||
rarely in minor releases. Formatting for `feature` entries differs
|
||
from normal changelog formatting - see the [new features
|
||
instructions](#new-and-major-features).
|
||
- `improvement` - Most updates to the product that aren’t `bug`s, but
|
||
aren't big enough to be a `feature`, will be an `improvement`.
|
||
|
||
2. A component (for example, `secret/pki` or `sdk/framework` or), a colon and a space, and then a one-line description of the change.
|
||
|
||
3. An ending code block.
|
||
|
||
This should be in a file named after the pull request number (e.g., `12345.txt`).
|
||
|
||
There are many examples in this folder; check one out if you're stuck!
|
||
|
||
See [hashicorp/go-changelog](https://github.com/hashicorp/go-changelog) for full documentation on the supported entries.
|
||
|
||
## New and Major Features
|
||
|
||
For features we are introducing in a new major release, we prefer a single
|
||
changelog entry representing that feature. This way, it is clear to readers
|
||
what feature is being introduced. You do not need to reference a specific PR,
|
||
and the formatting is slightly different - your changelog file should look
|
||
like:
|
||
|
||
changelog/<pr num OR feature name>.txt:
|
||
```release-note:feature
|
||
**Feature Name**: Description of feature - for example "Custom password policies are now supported for all database engines."
|
||
```
|