[chloggen] Generate separate changelog for end users and Go API consumers

Author: djaglowski

.chloggen/TEMPLATE.yaml

@@ -1,6 +1,4 @@
 # Use this changelog template to create an entry for release notes.
-# If your change doesn't affect end users, such as a test fix or a tooling change,
-# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
 
 # One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
 change_type:
@@ -18,3 +16,12 @@ issues: []
 # These lines will be padded with 2 spaces and then inserted directly into the document.
 # Use pipe (|) for multiline entries.
 subtext:
+
+# If your change doesn't affect end users or the exported elements of any package,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: []

.chloggen/chloggen-config.yaml

@@ -0,0 +1,27 @@
+# Use this changelog template to create an entry for release notes.
+
+# 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. filelogreceiver)
+component: changelog
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Generate separate changelogs for end users and package consumers
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [24014]
+
+# (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:
+
+# If your change doesn't affect end users or the exported elements of any package,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: [api]

.chloggen/config.yaml

@@ -0,0 +1,24 @@
+# The directory that stores individual changelog entries.
+# Each entry is stored in a dedicated yaml file.
+# - 'chloggen new' will copy the 'template_yaml' to this directory as a new entry file.
+# - 'chloggen validate' will validate that all entry files are valid.
+# - 'chloggen update' will read and delete all entry files in this directory, and update 'changelog_md'.
+# Specify as relative path from root of repo.
+# (Optional) Default: .chloggen
+entries_dir: .chloggen
+
+# This file is used as the input for individual changelog entries.
+# Specify as relative path from root of repo.
+# (Optional) Default: .chloggen/TEMPLATE.yaml
+template_yaml: .chloggen/TEMPLATE.yaml
+
+# The CHANGELOG file or files to which 'chloggen update' will write new entries
+# (Optional) Default filename: CHANGELOG.md
+change_logs:
+  user: CHANGELOG.md
+  api: CHANGELOG-API.md
+
+# The default change_log or change_logs to which an entry should be added.
+# If 'change_logs' is specified in this file, and no value is specified for 'default_change_logs',
+# then 'change_logs' MUST be specified in every entry file.
+default_change_logs: [user]

.chloggen/heartbeat-while-startup.yaml

@@ -18,3 +18,5 @@ issues: [24411]
 # These lines will be padded with 2 spaces and then inserted directly into the document.
 # Use pipe (|) for multiline entries.
 subtext:
+
+change_logs: [user, api]

.chloggen/k8sclusterreceiver-enable-disable-metrics.yaml

@@ -18,3 +18,5 @@ issues: [24568]
 # These lines will be padded with 2 spaces and then inserted directly into the document.
 # Use pipe (|) for multiline entries.
 subtext:
+
+change_logs: [user, api]

.chloggen/mdatagen-avoid-reusing-resource-builder.yaml

@@ -13,3 +13,5 @@ note: Avoid reusing the same ResourceBuilder instance for multiple ResourceMetri
 
 # Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
 issues: [24762]
+
+change_logs: [user, api]

.chloggen/splunkhecreceiver-align-success-response.yaml

@@ -17,3 +17,5 @@ issues: [19219]
 # (optional) additional information to render under the primary note provided above;
 # these lines will be padded with two spaces and inserted directly into the document
 subtext: changes resp from plaintext "ok" to json {"text"："success", "code"：0}
+
+change_logs: [user, api]

.github/workflows/changelog.yml

@@ -43,18 +43,18 @@ jobs:
             ~/go/pkg/mod
           key: changelog-${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
 
-      - name: Ensure no changes to the CHANGELOG
+      - name: Ensure no changes to the CHANGELOG.md or CHANGELOG-API.md
         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]')}}
         run: |
-          if [[ $(git diff --name-only $(git merge-base origin/main ${{ github.event.pull_request.head.sha }}) ${{ github.event.pull_request.head.sha }} ./CHANGELOG.md) ]]
+          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 "The CHANGELOG should not be directly modified."
+            echo "CHANGELOG.md and CHANGELOG-API.md 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 "The CHANGELOG was not modified."
+            echo "CHANGELOG.md and CHANGELOG-API.md were not modified."
           fi
 
       - name: Ensure ./.chloggen/*.yaml addition(s)

CHANGELOG-API.md

@@ -0,0 +1,8 @@
+<!-- This file is autogenerated. See CONTRIBUTING.md for instructions to add an entry. -->
+
+# GO API Changelog
+
+This changelog includes only developer-facing changes.
+If you are looking for user-facing changes, check out [CHANGELOG.md](./CHANGELOG.md).
+
+<!-- next version -->

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 # Changelog
 
+Starting with version v0.83.0, this changelog includes only user-facing changes.
+If you are looking for developer-facing changes, check out [CHANGELOG-API.md](./CHANGELOG-API.md).
+
 <!-- next version -->
 
 ## v0.82.0

CONTRIBUTING.md

@@ -13,13 +13,22 @@ change. For instance:
 
 ## Changelog
 
+### Overview
+
+There are two Changelogs for this repository:
+
+- `CHANGELOG.md` is intended for users of the collector and lists changes that affect the behavior of the collector.
+- `CHANGELOG-API.md` is intended for developers who are importing packages from the collector codebase.
+
+### When to add a Changelog Entry
+
 Pull requests that contain user-facing changes will require a changelog entry. Keep in mind the following types of users:
 1. Those who are consuming the telemetry exported from the collector
 2. Those who are deploying or otherwise managing the collector or its configuration
 3. Those who are depending on APIs exported from collector packages
 4. Those who are contributing to the repository
 
-The changelog is primarily directed at the first three groups but it is sometimes appropriate to include important updates relevant only to the forth group.
+Changes that affect the first two groups should be noted in `CHANGELOG.md`. Changes that affect the third or forth groups should be noted in `CHANGELOG-API.md`.
 
 If a changelog entry is not required, a maintainer or approver will add the `Skip Changelog` label to the pull request.
 
@@ -45,11 +54,11 @@ No changelog entry:
 
 ### Adding a Changelog Entry
 
-The [CHANGELOG.md](./CHANGELOG.md) file in this repo is autogenerated from `.yaml` files in the `./.chloggen` directory.
+The [CHANGELOG.md](./CHANGELOG.md) and [CHANGELOG-API.md](./CHANGELOG-API.md) files 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.
+During the collector release process, all `./chloggen/*.yaml` files are transcribed into `CHANGELOG.md` and `CHANGELOG-API.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`)

Makefile

@@ -263,19 +263,19 @@ update-codeowners: gengithub generate
 FILENAME?=$(shell git branch --show-current)
 .PHONY: chlog-new
 chlog-new: $(CHLOGGEN)
-	$(CHLOGGEN) new --filename $(FILENAME)
+	$(CHLOGGEN) new --config $(CHLOGGEN_CONFIG) --filename $(FILENAME)
 
 .PHONY: chlog-validate
 chlog-validate: $(CHLOGGEN)
-	$(CHLOGGEN) validate
+	$(CHLOGGEN) validate --config $(CHLOGGEN_CONFIG)
 
 .PHONY: chlog-preview
 chlog-preview: $(CHLOGGEN)
-	$(CHLOGGEN) update --dry
+	$(CHLOGGEN) update --config $(CHLOGGEN_CONFIG) --dry
 
 .PHONY: chlog-update
 chlog-update: $(CHLOGGEN)
-	$(CHLOGGEN) update --version $(VERSION)
+	$(CHLOGGEN) update --config $(CHLOGGEN_CONFIG) --version $(VERSION)
 
 .PHONY: genotelcontribcol
 genotelcontribcol: $(BUILDER)

Makefile.Common

@@ -34,6 +34,7 @@ TOOLS_MOD_REGEX  := "\s+_\s+\".*\""
 TOOLS_PKG_NAMES  := $(shell grep -E $(TOOLS_MOD_REGEX) < $(TOOLS_MOD_DIR)/tools.go | tr -d " _\"")
 TOOLS_BIN_DIR    := $(SRC_ROOT)/.tools
 TOOLS_BIN_NAMES  := $(addprefix $(TOOLS_BIN_DIR)/, $(notdir $(TOOLS_PKG_NAMES)))
+CHLOGGEN_CONFIG  := .chloggen/config.yaml
 
 .PHONY: install-tools
 install-tools: $(TOOLS_BIN_NAMES)

internal/tools/go.mod

@@ -10,7 +10,7 @@ require (
 	github.com/jcchavezs/porto v0.4.0
 	github.com/jstemmer/go-junit-report v1.0.0
 	go.opentelemetry.io/build-tools/checkfile v0.10.0
-	go.opentelemetry.io/build-tools/chloggen v0.9.0
+	go.opentelemetry.io/build-tools/chloggen v0.11.0
 	go.opentelemetry.io/build-tools/crosslink v0.9.0
 	go.opentelemetry.io/build-tools/issuegenerator v0.9.0
 	go.opentelemetry.io/build-tools/multimod v0.9.0