Protect released changelog in CI (#5906)

Mirror of open-telemetry/opentelemetry-go#5560.
It also includes the fix from
open-telemetry/opentelemetry-go#5616

---------

Co-authored-by: Damien Mathieu <42@dmathieu.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: |
+          ./tools/verify_released_changelog.sh ${{ github.base_ref }}

CHANGELOG.md

@@ -17,6 +17,9 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 - The deprecated `go.opentelemetry.io/contrib/processors/baggagecopy` package is removed. (#5853)
 
+<!-- Released section -->
+<!-- Don't change this section unless doing release -->
+
 ## [1.28.0/0.53.0/0.22.0/0.8.0/0.3.0/0.1.0] - 2024-07-02
 
 ### Added
@@ -1132,6 +1135,8 @@ First official tagged release of `contrib` repository.
 [0.7.0]: https://github.com/open-telemetry/opentelemetry-go-contrib/releases/tag/v0.7.0
 [0.6.1]: https://github.com/open-telemetry/opentelemetry-go-contrib/releases/tag/v0.6.1
 
+<!-- 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

@@ -108,6 +108,9 @@ since the last release tag.
 git --no-pager log --pretty=oneline "<last tag>..HEAD"
 ```
 
+Make sure the new released section is under the comment for released section,
+like `<!-- Released section -->`, so it is protected from being overwritten in the future.
+
 Be sure to update all the appropriate links at the bottom of the file.
 
 Finally, commit this change to your release branch.

tools/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."