diff --git a/.changelog/changelog.tmpl b/.changelog/changelog.tmpl new file mode 100644 index 0000000000..c1de4293b9 --- /dev/null +++ b/.changelog/changelog.tmpl @@ -0,0 +1,57 @@ +{{- if index .NotesByType "breaking-change" -}} +BREAKING CHANGES: + +{{range index .NotesByType "breaking-change" -}} +* {{ template "note" . }} +{{ end -}} +{{- end -}} + +{{- if .NotesByType.security }} +SECURITY: + +{{range .NotesByType.security -}} +* {{ template "note" . }} +{{ end -}} +{{- end -}} + +{{- if .NotesByType.feature }} +FEATURES: + +{{range .NotesByType.feature -}} +* {{ template "note" . }} +{{ end -}} +{{- end -}} + +{{- $improvements := combineTypes .NotesByType.improvement .NotesByType.enhancement -}} +{{- if $improvements }} +IMPROVEMENTS: + +{{range $improvements | sort -}} +* {{ template "note" . }} +{{ end -}} +{{- end -}} + +{{- if .NotesByType.deprecation }} +DEPRECATIONS: + +{{range .NotesByType.deprecation -}} +* {{ template "note" . }} +{{ end -}} +{{- end -}} + +{{- if .NotesByType.bug }} +BUG FIXES: + +{{range .NotesByType.bug -}} +* {{ template "note" . }} +{{ end -}} +{{- end -}} + +{{- if .NotesByType.note }} +NOTES: + +{{range .NotesByType.note -}} +* {{ template "note" . }} +{{ end -}} +{{- end -}} + diff --git a/.changelog/note.tmpl b/.changelog/note.tmpl new file mode 100644 index 0000000000..7588c65fd4 --- /dev/null +++ b/.changelog/note.tmpl @@ -0,0 +1,3 @@ +{{- define "note" -}} +{{.Body}}{{if not (stringHasPrefix .Issue "_")}} [[GH-{{- .Issue -}}](https://github.com/hashicorp/consul-k8s/issues/{{- .Issue -}})]{{end}} +{{- end -}} diff --git a/.github/workflows/changelog-checker.yml b/.github/workflows/changelog-checker.yml new file mode 100644 index 0000000000..bb13255d29 --- /dev/null +++ b/.github/workflows/changelog-checker.yml @@ -0,0 +1,46 @@ +# This workflow checks that there is either a 'pr/no-changelog' label applied to a PR +# or there is a .changelog/.txt file associated with a PR for a changelog entry + +name: Changelog Checker + +on: + pull_request: + types: [opened, synchronize, labeled] + # Runs on PRs to main and all release branches + branches: + - main + - release/* + +jobs: + # checks that a .changelog entry is present for a PR + changelog-check: + # If there a `pr/no-changelog` label we ignore this check. Also, we ignore PRs created by the bot assigned to `backport-assistant` + if: "! ( contains(github.event.pull_request.labels.*.name, 'pr/no-changelog') || github.event.pull_request.user.login == 'hc-github-team-consul-core' )" + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v2 + with: + ref: ${{ github.event.pull_request.head.sha }} + fetch-depth: 0 # by default the checkout action doesn't checkout all branches + - name: Check for changelog entry in diff + run: | + # check if there is a diff in the .changelog directory + # for PRs against the main branch, the changelog file name should match the PR number + if [ "${{ github.event.pull_request.base.ref }}" = "${{ github.event.repository.default_branch }}" ]; then + enforce_matching_pull_request_number="matching this PR number " + changelog_file_path=".changelog/(_)?${{ github.event.pull_request.number }}.txt" + else + changelog_file_path=".changelog/[_0-9]*.txt" + fi + + changelog_files=$(git --no-pager diff --name-only HEAD "$(git merge-base HEAD "origin/main")" | egrep ${changelog_file_path}) + + # If we do not find a file in .changelog/, we fail the check + if [ -z "$changelog_files" ]; then + # Fail status check when no .changelog entry was found on the PR + echo "Did not find a .changelog entry ${enforce_matching_pull_request_number}and the 'pr/no-changelog' label was not applied. Reference - https://github.com/hashicorp/consul/pull/8387" + exit 1 + else + echo "Found .changelog entry in PR!" + fi diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 510d4c3b3f..8e634e323e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,6 +24,7 @@ 1. [Writing Acceptance tests](#writing-acceptance-tests) 1. [Using the Acceptance Test Framework to Debug](#using-acceptance-test-framework-to-debug) 1. [Helm Reference Docs](#helm-reference-docs) +1. [Adding a Changelog Entry](#adding-a-changelog-entry) ## Contributing 101 @@ -1214,3 +1215,43 @@ So that the documentation can look like: ```markdown - `ports` ((#v-ingressgateways-defaults-service-ports)) (`array: [{port: 8080, port: 8443}]`) - Port docs ``` + +## Adding a Changelog Entry + +Any change that a Consul-K8s user might need to know about should have a changelog entry. + +What doesn't need a changelog entry? +- Typos/fixes, unless they are in a public-facing API +- Code changes we are certain no Consul-K8s users will need to know about + +To include a [changelog entry](../.changelog) in a PR, commit a text file +named `.changelog/.txt`, where `` is the number associated with the open +PR in GitHub. The text file should describe the changes in the following format: + +```` +```release-note: +: +``` +```` + +Valid values for `` include: +- `feature`: for the addition of a new feature +- `improvement`: for an improvement (not a bug fix) to an existing feature +- `bug`: for a bug fix +- `security`: for any Common Vulnerabilities and Exposures (CVE) resolutions +- `breaking-change`: for any change that is not fully backwards-compatible +- `deprecation`: for functionality which is now marked for removal in a future release + +`` is meant to categorize the functionality affected by the change. +Some common values are: +- `cli`: related to the command-line interface and its commands +- `control-plane`: related to control-plane functionality +- `helm`: related to the charts module and any files, yaml, go, etc. therein + +There may be cases where a `code area` doesn't make sense (i.e. addressing a Go CVE). In these +cases it is okay not to provide a `code area`. + +For more examples, look in the [`.changelog/`](../.changelog) folder for existing changelog entries. + +If a PR deserves multiple changelog entries, just add multiple entries separated by a newline +in the format described above to the `.changelog/.txt` file. diff --git a/Makefile b/Makefile index 6ad59a2a91..daee6b693b 100644 --- a/Makefile +++ b/Makefile @@ -156,7 +156,7 @@ endif ifndef RELEASE_DATE $(error RELEASE_DATE is required, use format , (ex. October 4, 2022)) endif - source $(CURDIR)/control-plane/build-support/scripts/functions.sh; prepare_release $(CURDIR) $(RELEASE_VERSION) "$(RELEASE_DATE)" $(PRERELEASE_VERSION) + source $(CURDIR)/control-plane/build-support/scripts/functions.sh; prepare_release $(CURDIR) $(RELEASE_VERSION) "$(RELEASE_DATE)" $(LAST_RELEASE_GIT_TAG) $(PRERELEASE_VERSION) prepare-dev: ifndef RELEASE_VERSION @@ -168,7 +168,7 @@ endif ifndef NEXT_RELEASE_VERSION $(error NEXT_RELEASE_VERSION is required) endif - source $(CURDIR)/control-plane/build-support/scripts/functions.sh; prepare_dev $(CURDIR) $(RELEASE_VERSION) "$(RELEASE_DATE)" $(NEXT_RELEASE_VERSION) $(PRERELEASE_VERSION) + source $(CURDIR)/control-plane/build-support/scripts/functions.sh; prepare_dev $(CURDIR) $(RELEASE_VERSION) "$(RELEASE_DATE)" $(NEXT_RELEASE_VERSION) # ===========> Makefile config diff --git a/control-plane/build-support/functions/10-util.sh b/control-plane/build-support/functions/10-util.sh index b807d35397..8367c22743 100644 --- a/control-plane/build-support/functions/10-util.sh +++ b/control-plane/build-support/functions/10-util.sh @@ -684,94 +684,6 @@ function update_version_helm { return $? } -function set_changelog_version { - # Arguments: - # $1 - Path to top level Consul source - # $2 - Version to put into the Changelog - # $3 - Release Date - # - # Returns: - # 0 - success - # * - error - - local changelog="${1}/CHANGELOG.md" - local version="$2" - local rel_date="$3" - - if ! test -f "${changelog}" - then - err "ERROR: File not found: ${changelog}" - return 1 - fi - - if test -z "${version}" - then - err "ERROR: Must specify a version to put into the changelog" - return 1 - fi - - if test -z "${rel_date}" - then - rel_date=$(date +"%B %d, %Y") - fi - - sed_i ${SED_EXT} -e "s/## UNRELEASED/## ${version} (${rel_date})/" "${changelog}" - return $? -} - -function unset_changelog_version { - # Arguments: - # $1 - Path to top level Consul source - # - # Returns: - # 0 - success - # * - error - - local changelog="${1}/CHANGELOG.md" - - if ! test -f "${changelog}" - then - err "ERROR: File not found: ${changelog}" - return 1 - fi - - sed_i ${SED_EXT} -e "1 s/^## [0-9]+\.[0-9]+\.[0-9]+ \([^)]*\)/## UNRELEASED/" "${changelog}" - return $? -} - -function add_unreleased_to_changelog { - # Arguments: - # $1 - Path to top level Consul source - # - # Returns: - # 0 - success - # * - error - - local changelog="${1}/CHANGELOG.md" - - if ! test -f "${changelog}" - then - err "ERROR: File not found: ${changelog}" - return 1 - fi - - # Check if we are already in unreleased mode - if head -n 1 "${changelog}" | grep -q -c UNRELEASED - then - return 0 - fi - - local tfile="$(mktemp) -t "CHANGELOG.md_")" - ( - echo -e "## UNRELEASED\n" > "${tfile}" && - cat "${changelog}" >> "${tfile}" && - cp "${tfile}" "${changelog}" - ) - local ret=$? - rm "${tfile}" - return $ret -} - function set_version { # Arguments: # $1 - Path to top level Consul source @@ -803,21 +715,18 @@ function set_version { status_stage "==> Updating control-plane version/version.go with version info: ${vers} "$4"" if ! update_version "${sdir}/control-plane/version/version.go" "${vers}" "$4" then - unset_changelog_version "${sdir}" return 1 fi status_stage "==> Updating cli version/version.go with version info: ${vers} "$4"" if ! update_version "${sdir}/cli/version/version.go" "${vers}" "$4" then - unset_changelog_version "${sdir}" return 1 fi status_stage "==> Updating Helm chart versions with version info: ${vers} "$4"" if ! update_version_helm "${sdir}/charts/consul" "${vers}" "$4" "$5" then - unset_changelog_version "${sdir}" return 1 fi @@ -825,31 +734,52 @@ function set_version { } function set_changelog { - # Arguments: - # $1 - Path to top level Consul source - # $2 - The version of the release - # $3 - The release date - # $4 - The pre-release version - # - # - # Returns: - # 0 - success - # * - error - local sdir="$1" - local vers="$2" - local rel_date="$(date +"%B %d, %Y")" - if test -n "$3" - then - rel_date="$3" - fi + # Arguments: + # $1 - Path to top level Consul source + # $2 - Version + # $3 - Release Date + # $4 - The last git release tag + # + # + # Returns: + # 0 - success + # * - error - local changelog_vers="${vers}" - if test -n "$4" - then - changelog_vers="${vers}-$4" - fi - status_stage "==> Updating CHANGELOG.md with release info: ${changelog_vers} (${rel_date})" - set_changelog_version "${sdir}" "${changelog_vers}" "${rel_date}" || return 1 + # Check if changelog-build is installed + if ! command -v changelog-build &> /dev/null; then + echo "Error: changelog-build is not installed. Please install it and try again." + exit 1 + fi + + local curdir="$1" + local version="$2" + local rel_date="$(date +"%B %d, %Y")" + if test -n "$3" + then + rel_date="$3" + fi + local last_release_date_git_tag=$4 + + if test -z "${version}" + then + err "ERROR: Must specify a version to put into the changelog" + return 1 + fi + + if [ -z "$LAST_RELEASE_GIT_TAG" ]; then + echo "Error: LAST_RELEASE_GIT_TAG not specified." + exit 1 + fi + +cat < tmp && mv tmp "${curdir}"/CHANGELOG.MD +## ${version} (${rel_date}) +$(changelog-build -last-release ${LAST_RELEASE_GIT_TAG} \ + -entries-dir .changelog/ \ + -changelog-template .changelog/changelog.tmpl \ + -note-template .changelog/note.tmpl \ + -this-release $(git rev-parse HEAD)) + +EOT } function prepare_release { @@ -857,14 +787,16 @@ function prepare_release { # $1 - Path to top level Consul source # $2 - The version of the release # $3 - The release date - # $4 - The pre-release version + # $4 - The last release git tag for this branch (eg. v1.1.0) + # $5 - The pre-release version # # # Returns: # 0 - success # * - error - echo "release version: " $1 $2 $3 $4 - set_version "$1" "$2" "$3" "$4" "hashicorp\/consul-k8s-control-plane:" + + echo "release version: " "$1" "$2" "$3" "$4" + set_version "$1" "$2" "$3" "$5" "hashicorp\/consul-k8s-control-plane:" set_changelog "$1" "$2" "$3" "$4" } @@ -874,22 +806,15 @@ function prepare_dev { # $2 - The version of the release # $3 - The release date # $4 - The version of the next release - # $5 - The pre-release version (for setting beta in changelog) + # $5 - The last release git tag for this branch (eg. v1.1.0) # # Returns: # 0 - success # * - error echo "dev version: " $1 $4 $3 "dev" - - local sdir="$1" - - set_changelog "$1" "$2" "$3" "$5" set_version "$1" "$4" "$3" "dev" "docker.mirror.hashicorp.services\/hashicorppreview\/consul-k8s-control-plane:" - status_stage "==> Adding new UNRELEASED label in CHANGELOG.md" - add_unreleased_to_changelog "${sdir}" || return 1 - return 0 }