[chore] add chloggen for changelog

codeboten · Alex Boten · commit 9a7f60d4cac3 · 2022-10-13T08:20:15.000-07:00
This change updates the changelog process in this repo to match the process in the contrib repo.
diff --git a/.chloggen/TEMPLATE.yaml b/.chloggen/TEMPLATE.yaml
@@ -0,0 +1,16 @@
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type:
+
+# The name of the component, or a single word describing the area of concern, (e.g. otlpreceiver)
+component:
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note:
+
+# One or more tracking issues or pull requests related to the change
+issues: []
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
diff --git a/.chloggen/instrument-otel-go.yaml b/.chloggen/instrument-otel-go.yaml
@@ -0,0 +1,16 @@
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. otlpreceiver)
+component: obsreport
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: "Instrument `obsreport.Receiver` metrics with otel-go"
+
+# One or more tracking issues or pull requests related to the change
+issues: [6222]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml
@@ -20,19 +20,63 @@ jobs:
     if: ${{ !contains(github.event.pull_request.labels.*.name, 'dependencies') && !contains(github.event.pull_request.labels.*.name, 'Skip Changelog') && !contains(github.event.pull_request.title, '[chore]')}}
 
     steps:
-      - uses: actions/checkout@v3
+      - name: Checkout Repo
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Setup Go
+        uses: actions/setup-go@v3
+        with:
+          go-version: 1.19
+      - name: Cache Go
+        id: go-cache
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/go/bin
+            ~/go/pkg/mod
+          key: changelog-${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
 
-      - name: Check for CHANGELOG changes
+      - name: Ensure no changes to the CHANGELOG
         run: |
-          # 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 ${{ github.base_ref }} --depth=1
-          if [[ $(git diff --name-only FETCH_HEAD | grep CHANGELOG) ]]
+          if [[ $(git diff --name-only $(git merge-base origin/main ${{ github.event.pull_request.head.sha }}) ${{ github.event.pull_request.head.sha }} ./CHANGELOG.md) ]]
           then
-            echo "A CHANGELOG was modified. Looks good!"
+            echo "The CHANGELOG should not be directly modified."
+            echo "Please add a .yaml file to the ./.chloggen/ directory."
+            echo "See CONTRIBUTING.md for more details."
+            echo "Alternately, add either \"[chore]\" to the title of the pull request or add the \"Skip Changelog\" label if this job should be skipped."
+            false
           else
-            echo "No CHANGELOG was modified."
-            echo "Please add a CHANGELOG entry, or add either \"[chore]\" to the title of the pull request or add the \"Skip Changelog\" label if not required."
+            echo "The CHANGELOG was not modified."
+          fi
+
+      - name: Ensure ./.chloggen/*.yaml addition(s)
+        run: |
+          if [[ 1 -gt $(git diff --diff-filter=A --name-only $(git merge-base origin/main ${{ github.event.pull_request.head.sha }}) ${{ github.event.pull_request.head.sha }} ./.chloggen | grep -c \\.yaml) ]]
+          then
+            echo "No changelog entry was added to the ./.chloggen/ directory."
+            echo "Please add a .yaml file to the ./.chloggen/ directory."
+            echo "See CONTRIBUTING.md for more details."
+            echo "Alternately, add either \"[chore]\" to the title of the pull request or add the \"Skip Changelog\" label if this job should be skipped."
             false
+          else
+            echo "A changelog entry was added to the ./.chloggen/ directory."
           fi
+
+      - name: Validate ./.chloggen/*.yaml changes
+        run: |
+          make chlog-validate \
+            || { echo "New ./.chloggen/*.yaml file failed validation."; exit 1; }
+
+      # In order to validate any links in the yaml file, render the config to markdown
+      - name: Render .chloggen changelog entries
+        run: make chlog-preview > changelog_preview.md
+      - name: Install markdown-link-check
+        run: npm install -g markdown-link-check
+      - name: Run markdown-link-check
+        run: |
+          markdown-link-check \
+            --verbose \
+            --config .github/workflows/check_links_config.json \
+            changelog_preview.md \
+            || { echo "Check that anchor links are lowercase"; exit 1; }
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,10 +1,8 @@
-# Changelog
-
-## Unreleased
+<!-- This file is autogenerated. See CONTRIBUTING.md for instructions to add an entry. -->
 
-### 💡 Enhancements 💡
+# Changelog
 
-- Instrument `obsreport.Receiver` metrics with otel-go (#6222)
+<!-- next version -->
 
 ## v0.62.0 Beta
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -492,9 +492,9 @@ changes in the specification can result in breaking changes to the implementatio
 policy of the Collector SIG to not implement, or accept implementations of, new or changed specification language
 prior to inclusion in a stable release of the specification.
 
-## Updating Changelog
+## Changelog
 
-An entry into the [Changelog](./CHANGELOG.md) is required for the following reasons:
+An entry into the changelog is required for the following reasons:
 
 - Changes made to the behaviour of the component
 - Changes to the configuration
@@ -509,6 +509,22 @@ It is reasonable to omit an entry to the changelog under these circuimstances:
 If there is some uncertainty with regards to if a changelog entry is needed, the recomendation is to create
 an entry to in the event that the change is important to the project consumers.
 
+### Adding a Changelog Entry
+
+The [CHANGELOG.md](./CHANGELOG.md) file in this repo is autogenerated from `.yaml` files in the `./.chloggen` directory.
+
+Your pull-request should add a new `.yaml` file to this directory. The name of your file must be unique since the last release.
+
+During the collector release process, all `./chloggen/*.yaml` files are transcribed into `CHANGELOG.md` and then deleted.
+
+**Recommended Steps**
+1. Create an entry file using `make chlog-new`. This generates a file based on your current branch (e.g. `./.chloggen/my-branch.yaml`)
+2. Fill in all fields in the new file
+3. Run `make chlog-validate` to ensure the new file is valid
+4. Commit and push the file
+
+Alternately, copy `./.chloggen/TEMPLATE.yaml`, or just create your file from scratch.
+
 ## Release
 
 See [release](docs/release.md) for details.
diff --git a/Makefile b/Makefile
@@ -134,6 +134,7 @@ install-tools:
 	cd $(TOOLS_MOD_DIR) && $(GOCMD) install github.com/tcnksm/ghr
 	cd $(TOOLS_MOD_DIR) && $(GOCMD) install github.com/wadey/gocovmerge
 	cd $(TOOLS_MOD_DIR) && $(GOCMD) install go.opentelemetry.io/build-tools/checkdoc
+	cd $(TOOLS_MOD_DIR) && $(GOCMD) install go.opentelemetry.io/build-tools/chloggen
 	cd $(TOOLS_MOD_DIR) && $(GOCMD) install go.opentelemetry.io/build-tools/semconvgen
 	cd $(TOOLS_MOD_DIR) && $(GOCMD) install golang.org/x/exp/cmd/apidiff
 	cd $(TOOLS_MOD_DIR) && $(GOCMD) install golang.org/x/tools/cmd/goimports
@@ -441,3 +442,24 @@ checklinks:
 crosslink: 
 	@echo "Executing crosslink"
 	crosslink --root=$(shell pwd) --prune
+
+.PHONY: chlog-install
+chlog-install:
+	cd $(TOOLS_MOD_DIR) && $(GOCMD) install go.opentelemetry.io/build-tools/chloggen
+
+FILENAME?=$(shell git branch --show-current)
+.PHONY: chlog-new
+chlog-new: chlog-install
+	chloggen new --filename $(FILENAME)
+
+.PHONY: chlog-validate
+chlog-validate: chlog-install
+	chloggen validate
+
+.PHONY: chlog-preview
+chlog-preview: chlog-install
+	chloggen update --dry
+
+.PHONY: chlog-update
+chlog-update: chlog-install
+	chloggen update --version $(VERSION)
diff --git a/docs/release.md b/docs/release.md
@@ -37,7 +37,8 @@ It is possible that a core approver isn't a contrib approver. In that case, the
 
 1. Prepare Core for release.
 
-    * Update CHANGELOG.md file and rename the Unreleased section to the new release name. Add a new unreleased section at top. Use commit history feature to get the list of commits since the last release to help understand what should be in the release notes, e.g.: https://github.com/open-telemetry/opentelemetry-collector/compare/v0.44.0...main. Commit the changes.
+    * Update CHANGELOG.md file, this is done via `chloggen`. Run the following command from the root of the opentelemetry-collector-contrib repo:
+      * `make chlog-update VERSION=v0.55.0`
 
     * Run `make prepare-release PREVIOUS_VERSION=0.52.0 RELEASE_CANDIDATE=0.53.0`
 
@@ -59,7 +60,7 @@ It is possible that a core approver isn't a contrib approver. In that case, the
 
 1. Prepare Contrib for release.
 
-  * Update CHANGELOG.md file, this is now done via `chloggen`. Run the following command from the root of the opentelemetry-collector-contrib repo:
+  * Update CHANGELOG.md file, this is done via `chloggen`. Run the following command from the root of the opentelemetry-collector-contrib repo:
       * `make chlog-update VERSION=v0.55.0`
 
   * Use multimod to update the version of the collector package:
diff --git a/internal/tools/go.mod b/internal/tools/go.mod
@@ -12,6 +12,7 @@ require (
 	github.com/tcnksm/ghr v0.16.0
 	github.com/wadey/gocovmerge v0.0.0-20160331181800-b5bfa59ec0ad
 	go.opentelemetry.io/build-tools/checkdoc v0.1.0
+	go.opentelemetry.io/build-tools/chloggen v0.1.0
 	go.opentelemetry.io/build-tools/crosslink v0.1.0
 	go.opentelemetry.io/build-tools/multimod v0.1.0
 	go.opentelemetry.io/build-tools/semconvgen v0.1.0
diff --git a/internal/tools/go.sum b/internal/tools/go.sum
@@ -701,6 +701,8 @@ go.opentelemetry.io/build-tools v0.1.0 h1:igm6n4IH+RNuwHDtcHFuO6UoGcY7ndZQoIxIL2
 go.opentelemetry.io/build-tools v0.1.0/go.mod h1:DrJ+yXmVxJFBLsfINMJ5XS9SF5tszV+Hnz/BgehnN70=
 go.opentelemetry.io/build-tools/checkdoc v0.1.0 h1:CJ9Bwu+DK97IPTpQKck748TAuZqcWuZCsVvh32D80/w=
 go.opentelemetry.io/build-tools/checkdoc v0.1.0/go.mod h1:su7j2uCbwFLI+wY9OI75qoCIehufSjd8SMTZgNGF67s=
+go.opentelemetry.io/build-tools/chloggen v0.1.0 h1:535UasQVHK3DC2SZKNYlGy3BeKusvmc8/vamZmvipfE=
+go.opentelemetry.io/build-tools/chloggen v0.1.0/go.mod h1:qsKC2l0n7+Pta8GqKN9vHxMPHwknQH0tjAfJaW1KWaU=
 go.opentelemetry.io/build-tools/crosslink v0.1.0 h1:yiPARvwtw7AI2uIafkodREE7Hl1AFmmTka32EqTYktA=
 go.opentelemetry.io/build-tools/crosslink v0.1.0/go.mod h1:xkaBbu3Q/ZBUYoP8IrKAwp6u4LHvElymHUccqdK5hC4=
 go.opentelemetry.io/build-tools/multimod v0.1.0 h1:TXxCjq00Lc/YYHUZ4DE8gNi+oYlpqgu2b7GXIt5oitk=
diff --git a/internal/tools/tools.go b/internal/tools/tools.go
@@ -32,6 +32,7 @@ import (
 	_ "github.com/tcnksm/ghr"
 	_ "github.com/wadey/gocovmerge"
 	_ "go.opentelemetry.io/build-tools/checkdoc"
+	_ "go.opentelemetry.io/build-tools/chloggen"
 	_ "go.opentelemetry.io/build-tools/crosslink"
 	_ "go.opentelemetry.io/build-tools/multimod"
 	_ "go.opentelemetry.io/build-tools/semconvgen"
