Protect released changelog in CI (#5560)

resolve #1682

This PR adds a new action in CI to protect released sections in the
changelog from being changed. It compares the released sections in the
changelog from the base branch to the current PR. It fails if a change
happens.

Apply "Unlock Released Changelog" to bypass this check when doing a new
release.

Action result if we changed the unreleased section:
d640deb435
Action result if we changed the released section:
d672de7a54

---

Meaning of `awk '/^\<!-- Released section --\>/ {flag=1} /^\<!--
Released section ended --\>/ {flag=0} flag'`
- `/^\<!-- Released section --\>/ {flag=1}`
  - Matches lines starting with `<!-- Released section -->`.
  - Sets the flag variable to 1 (starting the printing of lines).
- `/^\<!-- Released section ended --\>/ {flag=0}`
  - Matches lines starting with `<!-- Released section ended -->`.
  - Sets the flag variable to 0.
  - So it is ok to change external reference links, like
    ```md 
    [Go 1.22]: https://go.dev/doc/go1.22
    [Go 1.21]: https://go.dev/doc/go1.21
    ```
- `flag` lines are printed only when the flag is 1.

---------

Co-authored-by: Robert Pająk <pellared@hotmail.com>

.github/workflows/protect-released-changelog.yml

@@ -0,0 +1,20 @@
+# This action against that any PR targeting the main branch touches released
+# sections in CHANGELOG file. If change to released CHANGELOG is required, like
+# doing a release, add the \"Unlock Released Changelog\" label to disable this action.
+
+name: Protect released changelog
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+jobs:
+  protect-released-changelog:
+    runs-on: ubuntu-latest
+    if: ${{ !contains(github.event.pull_request.labels.*.name, 'Unlock Released Changelog')}}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Protect the released changelog
+        run: |
+          ./verify_released_changelog.sh ${{ github.base_ref }}

CHANGELOG.md

@@ -8,6 +8,9 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+<!-- Released section -->
+<!-- Don't change this section unless doing release -->
+
 ## [1.28.0/0.50.0/0.4.0] 2024-07-02
 
 ### Added
@@ -3087,6 +3090,8 @@ It contains api and sdk for trace and meter.
 [0.1.1]: https://github.com/open-telemetry/opentelemetry-go/releases/tag/v0.1.1
 [0.1.0]: https://github.com/open-telemetry/opentelemetry-go/releases/tag/v0.1.0
 
+<!-- Released section ended -->
+
 [Go 1.22]: https://go.dev/doc/go1.22
 [Go 1.21]: https://go.dev/doc/go1.21
 [Go 1.20]: https://go.dev/doc/go1.20

RELEASING.md

@@ -69,6 +69,7 @@ Update go.mod for submodules to depend on the new release which will happen in t
        ```
 
    - Move all the `Unreleased` changes into a new section following the title scheme (`[<new tag>] - <date of release>`).
+   - Make sure the new section is under the comment for released section, like `<!-- Released section -->`, so it is protected from being overwritten in the future.
    - Update all the appropriate links at the bottom.
 
 4. Push the changes to upstream and create a Pull Request on GitHub.

verify_released_changelog.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+set -euo pipefail
+
+TARGET="${1:?Must provide target ref}"
+
+FILE="CHANGELOG.md"
+TEMP_DIR=$(mktemp -d)
+echo "Temp folder: $TEMP_DIR"
+
+# Only the latest commit of the feature branch is available
+# automatically. To diff with the base branch, we need to
+# fetch that too (and we only need its latest commit).
+git fetch origin "${TARGET}" --depth=1
+
+# Checkout the previous version on the base branch of the changelog to tmpfolder
+git --work-tree="$TEMP_DIR" checkout FETCH_HEAD $FILE
+
+PREVIOUS_FILE="$TEMP_DIR/$FILE"
+CURRENT_FILE="$FILE"
+PREVIOUS_LOCKED_FILE="$TEMP_DIR/previous_locked_section.md"
+CURRENT_LOCKED_FILE="$TEMP_DIR/current_locked_section.md"
+
+# Extract released sections from the previous version
+awk '/^\<!-- Released section --\>/ {flag=1} /^\<!-- Released section ended --\>/ {flag=0} flag' "$PREVIOUS_FILE" > "$PREVIOUS_LOCKED_FILE"
+
+# Extract released sections from the current version
+awk '/^\<!-- Released section --\>/ {flag=1} /^\<!-- Released section ended --\>/ {flag=0} flag' "$CURRENT_FILE" > "$CURRENT_LOCKED_FILE"
+
+# Compare the released sections
+if ! diff -q "$PREVIOUS_LOCKED_FILE" "$CURRENT_LOCKED_FILE"; then
+    echo "Error: The released sections of the changelog file have been modified."
+    diff "$PREVIOUS_LOCKED_FILE" "$CURRENT_LOCKED_FILE"
+    rm -rf "$TEMP_DIR"
+    false
+fi
+
+rm -rf "$TEMP_DIR"
+echo "The released sections remain unchanged."