From 54b6cb9afea54b20a5774b2e41bdc80b4ac4bae0 Mon Sep 17 00:00:00 2001 From: Alexander Scheel Date: Mon, 6 Jun 2022 10:04:48 -0400 Subject: [PATCH] Add more documentation on changelogs (#15701) * Add more documentation on changelogs Signed-off-by: Alexander Scheel * Add description of modes --- changelog/README.md | 55 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 54 insertions(+), 1 deletion(-) diff --git a/changelog/README.md b/changelog/README.md index cf49db426..cbf841f6c 100644 --- a/changelog/README.md +++ b/changelog/README.md @@ -1,3 +1,56 @@ # changelog -This folder holds changelog updates from commit 3bc7d15 onwards. See [hashicorp/go-changelog](https://github.com/hashicorp/go-changelog) for full documentation on the supported entries. +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:` 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/.txt: + ```release-note:feature + **Feature Name**: Description of feature - for example "Custom password policies are now supported for all database engines." + ```