diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 2f3a9a769..1f86c3d89 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -23,6 +23,7 @@ Fixes ${ISSUE_URL} ### Tracking +* [ ] I added a new entry in an appropriate subdirectory of `changelog.d` * [ ] I mentioned this PR in Jira, OR I mentioned the Jira ticket in this PR. * [ ] I mentioned this PR in one of the issues attached to one of our repositories. diff --git a/.github/workflows/changelog-verify.yml b/.github/workflows/changelog-verify.yml new file mode 100644 index 000000000..916f4f81c --- /dev/null +++ b/.github/workflows/changelog-verify.yml @@ -0,0 +1,47 @@ +name: Changelog verification +on: + pull_request: + branches: [master] + push: + branches: [master] + +permissions: + contents: read + +jobs: + commitlint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + submodules: true + fetch-depth: 0 + - name: Setup node + uses: actions/setup-node@v4 + with: + node-version: lts/* + - name: Install commitlint + run: npm install -D @commitlint/cli @commitlint/config-conventional + - name: Print versions + run: | + git --version + node --version + npm --version + npx commitlint --version + + - name: Validate current commit (last commit) with commitlint + run: | + echo "export default { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js + npx commitlint -g commitlint.config.js --last --verbose 2>/dev/null + + - name: Check for entry in changelog.d changes in the PR + run: | + BASE_SHA=${{ github.event.pull_request.base.sha }} + HEAD_SHA=${{ github.event.pull_request.head.sha }} + + CHANGED_FILES=$(git diff --name-only $BASE_SHA $HEAD_SHA -- changelog.d/ | grep -vE "^$") + + if [ -z "$CHANGED_FILES" ]; then + echo "No files changed in changelog.d/" + exit 1 + fi diff --git a/README.md b/README.md index 54f2fd9b5..5b4e99f36 100644 --- a/README.md +++ b/README.md @@ -24,3 +24,52 @@ All the documentation on how to make use of this repository is hosted on https:/ * `charts/` contains helm charts that can be installed on kubernetes. The charts are mirroed to S3 and can be used with `helm repo add wire https://s3-eu-west-1.amazonaws.com/public.wire.com/charts`. See the [Administrator's Guide](https://docs.wire.com) for more info. * `terraform/` contains some examples for provisioning servers. See the [Administrator's Guide](https://docs.wire.com) for more info. * `bin/` contains some helper bash scripts. Some are used in the [Administrator's Guide](https://docs.wire.com) when installing wire-server, and some are used for developers/maintainers of this repository. + +## PR Guidelines + +In most cases, the only required action when creating a PR is creating a changelog entry (see below). + +### Changelog entries + +Every PR should add a new file in the appropriate subdirectory of `changelog.d`, containing just the text of the corresponding changelog entry. There is no need to explicitly write a PR number, because the `mk-changelog.sh` script (used on release) will add it automatically at the end. The name of the file does not matter, but it should be unique to avoid unnecessary conflicts (e.g. use the branch name). Read more [here](https://docs.wire.com/developer/developer/changelog.html) + +Example: create the file ./changelog.d/2-wire-builds/wire-chart-bump-5.13 with one-line content like: +``` +Wire backend upgrade to 5.13, see [docs](link-to-docs) +``` + +All changelog entries in the `changelog.d/` directory must follow commit message standards based on the [Conventional Commits specification](https://github.com/conventional-changelog/commitlint/blob/master/@commitlint/config-conventional/src/index.ts). Below are examples of properly formatted commit messages for each subdirectory in our changelog structure, along with descriptions of what content belongs in each subdirectory. + +**NOTE**: The commit messages and changelog.d entries will be verified using the github workflow [Changelog verification](.github/workflows/changelog-verify.yml). + +#### Directory Structure + +##### 0-release-notes +This directory contains extra notes about the release. It is intended for high-level release notes that provide an overview of what's new, what's changed, and any important information about the release. This is typically used for communicating with stakeholders and end-users. + +*commit message example:* `release: v0.0.0 Major Release` + +##### 1-debian-builds +Contains notes about changes related to Debian package builds. This includes modifications to build scripts (e.g., `build_linux_pkgs.sh`), changes in dependencies, and any other updates related to the creation of Debian packages. + +*commit message example:* `fix(debian_build): resolve dependency issue for gngpg package` + +##### 2-wire-builds +Documents changes related to the `wire-builds` repository. This includes updates to the values directory, modifications to Helm charts for Wire components, and any other changes specific to the Wire builds process. + +*commit message example:* `feat(wire_build): add support for postgresql to support wire release 5.17.0` + +##### 3-deploy-builds +Used to document changes in deployment processes and upgrades. Examples include Kubernetes upgrades via Ansible, changes in the `/offline/tasks` directory, and other deployment-related modifications. + +*commit message example:* `feat(deploy): add support for Kubernetes 1.29.10` + +##### 4-docs +Contains documentation related to deployment or bundling processes. This includes updates to installation guides, configuration instructions, and any other relevant documentation. + +*commit message example:* `docs(deploy): add guide for wiab-demo solution` + +##### 5-bug-fixes +Documents bug fixes for any existing solutions. This includes fixes for issues in the deployment process, build scripts, or any other component of the project. + +*commit message example:* `fix(build): fix the postgresql dependency on old non-existing images` diff --git a/changelog.d/0-release-notes/.title b/changelog.d/0-release-notes/.title new file mode 100644 index 000000000..d754b17ca --- /dev/null +++ b/changelog.d/0-release-notes/.title @@ -0,0 +1 @@ +Release notes \ No newline at end of file diff --git a/changelog.d/1-debian-builds/.title b/changelog.d/1-debian-builds/.title new file mode 100644 index 000000000..d1563daab --- /dev/null +++ b/changelog.d/1-debian-builds/.title @@ -0,0 +1 @@ +Base OS dependencies \ No newline at end of file diff --git a/changelog.d/2-wire-builds/.title b/changelog.d/2-wire-builds/.title new file mode 100644 index 000000000..7fa4b7bd0 --- /dev/null +++ b/changelog.d/2-wire-builds/.title @@ -0,0 +1 @@ +Internal Dependencies \ No newline at end of file diff --git a/changelog.d/3-deploy-builds/.title b/changelog.d/3-deploy-builds/.title new file mode 100644 index 000000000..fe92586cd --- /dev/null +++ b/changelog.d/3-deploy-builds/.title @@ -0,0 +1 @@ +External dependencies \ No newline at end of file diff --git a/changelog.d/4-docs/.title b/changelog.d/4-docs/.title new file mode 100644 index 000000000..7d1420123 --- /dev/null +++ b/changelog.d/4-docs/.title @@ -0,0 +1 @@ +Offline Documentation \ No newline at end of file diff --git a/changelog.d/4-docs/enable-changelog b/changelog.d/4-docs/enable-changelog new file mode 100644 index 000000000..1270e9330 --- /dev/null +++ b/changelog.d/4-docs/enable-changelog @@ -0,0 +1 @@ +Enable changelog management in wire-server-deploy \ No newline at end of file diff --git a/changelog.d/5-bug-fixes/.title b/changelog.d/5-bug-fixes/.title new file mode 100644 index 000000000..23bcb1b64 --- /dev/null +++ b/changelog.d/5-bug-fixes/.title @@ -0,0 +1 @@ +Bug fixes and other updates \ No newline at end of file diff --git a/changelog.d/mk-changelog.sh b/changelog.d/mk-changelog.sh new file mode 100755 index 000000000..c9616788d --- /dev/null +++ b/changelog.d/mk-changelog.sh @@ -0,0 +1,54 @@ +#!/usr/bin/env bash + +set -euo pipefail +shopt -s nullglob + +DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" + +getPRNumber() { + git log --reverse --format=%s -- "$1" | sed -rn '1 { /\((#.*)\)$/ s|^.*\((#.*)\)$|\1|p; }' | grep "" || + echo "#PR_NOT_FOUND" +} + +for d in "$DIR"/*; do + if [[ ! -d "$d" ]]; then continue; fi + + entries=("$d"/*[^~]) + + if [[ ${#entries[@]} -eq 0 ]]; then continue; fi + + echo -n "## " + # shellcheck disable=SC1003 + sed '$ a\' "$d/.title" + echo "" + # shellcheck disable=SC2094 + for f in "${entries[@]}"; do + pr=$(getPRNumber "$f") + # shellcheck disable=SC1003 + < "$f" sed -r ' + # create a bullet point on the first line + 1 { s/^/\* /; } + + # indent subsequent lines + 1 !{ s/^/ /; } + + # replace ## with PR number throughout + s/##/'"$pr"'/g' | + ( + if grep -q -r '\(#[^)]\)' "$f"; then + cat + else + sed -r ' + # add PR number at the end (unless already present) + $ { /^.*\((#.*)\)$/ ! { s/$/ ('"$pr"')/; } } + ' + fi + ) | sed -r ' + # remove trailing whitespace + s/\s+$// + + # make sure there is a trailing newline + $ a\' + done + echo "" +done diff --git a/changelog.d/mk-cleanup.sh b/changelog.d/mk-cleanup.sh new file mode 100755 index 000000000..b483a6e60 --- /dev/null +++ b/changelog.d/mk-cleanup.sh @@ -0,0 +1,9 @@ +#!/usr/bin/env bash + +set -euo pipefail +shopt -s nullglob + +DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + +rm -f "$DIR"/*/* +git add "$DIR"