feat(changelog): WPB-16103 add changelog directory structure and scripts

.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.
 

.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

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`

changelog.d/0-release-notes/.title

@@ -0,0 +1 @@
+Release notes

changelog.d/1-debian-builds/.title

@@ -0,0 +1 @@
+Base OS dependencies

changelog.d/2-wire-builds/.title

@@ -0,0 +1 @@
+Internal Dependencies

changelog.d/3-deploy-builds/.title

@@ -0,0 +1 @@
+External dependencies

changelog.d/4-docs/.title

@@ -0,0 +1 @@
+Offline Documentation

changelog.d/4-docs/enable-changelog

@@ -0,0 +1 @@
+Enable changelog management in wire-server-deploy

changelog.d/5-bug-fixes/.title

@@ -0,0 +1 @@
+Bug fixes and other updates

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

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"