Generate separate changelog for end users and Go API consumers (open-telemetry#8153)

Corresponds to
open-telemetry/opentelemetry-collector-contrib#24771

Author: djaglowski

.chloggen/TEMPLATE.yaml

@@ -1,3 +1,5 @@
+# Use this changelog template to create an entry for release notes.
+
 # One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
 change_type:
 
@@ -14,3 +16,10 @@ issues: []
 # These lines will be padded with 2 spaces and then inserted directly into the document.
 # Use pipe (|) for multiline entries.
 subtext:
+
+# 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: [8153]
+
+# (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]

.github/workflows/changelog.yml

@@ -37,17 +37,17 @@ 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
         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 -->
 
 ## v1.0.0-rcv0014/v0.82.0

CONTRIBUTING.md

@@ -505,28 +505,39 @@ prior to inclusion in a stable release of the specification.
 
 ## 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
+
 An entry into the changelog is required for the following reasons:
 
 - Changes made to the behaviour of the component
 - Changes to the configuration
 - Changes to default settings
 - New components being added
+- Changes to exported elements of a package
 
 It is reasonable to omit an entry to the changelog under these circuimstances:
 
 - Updating test to remove flakiness or improve coverage
 - Updates to the CI/CD process
+- Updates to internal packages
 
 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.
+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

@@ -534,22 +534,23 @@ crosslink: $(CROSSLINK)
 	$(CROSSLINK) --root=$(shell pwd) --prune
 
 
-FILENAME?=$(shell git branch --show-current).yaml
+FILENAME?=$(shell git branch --show-current)
 .PHONY: chlog-new
-chlog-new: $(CHLOG)
-	$(CHLOG) new --filename $(FILENAME)
+chlog-new: $(CHLOGGEN)
+	$(CHLOGGEN) new --config $(CHLOGGEN_CONFIG) --filename $(FILENAME)
 
 .PHONY: chlog-validate
-chlog-validate: $(CHLOG)
-	$(CHLOG) validate
+chlog-validate: $(CHLOGGEN)
+	$(CHLOGGEN) validate --config $(CHLOGGEN_CONFIG)
 
 .PHONY: chlog-preview
-chlog-preview: $(CHLOG)
-	$(CHLOG) update --dry
+chlog-preview: $(CHLOGGEN)
+	$(CHLOGGEN) update --config $(CHLOGGEN_CONFIG) --dry
 
 .PHONY: chlog-update
-chlog-update: $(CHLOG)
-	$(CHLOG) update --version $(VERSION)
+chlog-update: $(CHLOGGEN)
+	$(CHLOGGEN) update --config $(CHLOGGEN_CONFIG) --version $(VERSION)
+
 
 .PHONY: builder-integration-test
 builder-integration-test: $(ENVSUBST)

Makefile.Common

@@ -14,11 +14,12 @@ TOOLS_BIN_DIR   := $(PWD)/.tools
 TOOLS_MOD_REGEX := "\s+_\s+\".*\""
 TOOLS_PKG_NAMES := $(shell grep -E $(TOOLS_MOD_REGEX) < $(TOOLS_MOD_DIR)/tools.go | tr -d " _\"" | grep -vE '/v[0-9]+$$')
 TOOLS_BIN_NAMES := $(addprefix $(TOOLS_BIN_DIR)/, $(notdir $(shell echo $(TOOLS_PKG_NAMES))))
+CHLOGGEN_CONFIG := .chloggen/config.yaml
 
 ADDLICENSE   := $(TOOLS_BIN_DIR)/addlicense
 APIDIFF      := $(TOOLS_BIN_DIR)/apidiff
 CHECKFILE    := $(TOOLS_BIN_DIR)/checkfile
-CHLOG        := $(TOOLS_BIN_DIR)/chloggen
+CHLOGGEN     := $(TOOLS_BIN_DIR)/chloggen
 CROSSLINK    := $(TOOLS_BIN_DIR)/crosslink
 ENVSUBST     := $(TOOLS_BIN_DIR)/envsubst
 GOIMPORTS    := $(TOOLS_BIN_DIR)/goimports

internal/tools/go.mod

@@ -12,7 +12,7 @@ require (
 	github.com/mikefarah/yq/v4 v4.34.2
 	github.com/pavius/impi v0.0.3
 	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/multimod v0.9.0
 	go.opentelemetry.io/build-tools/semconvgen v0.9.0

internal/tools/go.sum

@@ -652,8 +652,8 @@ go.opentelemetry.io/build-tools v0.10.0 h1:5asgwud1lI/pMYQM9P/vwEgOjyv6G3nhYnwo0
 go.opentelemetry.io/build-tools v0.10.0/go.mod h1:GFpz8YD/DG5shfY1J2f3uuK88zr61U5rVRGOhKMDE9M=
 go.opentelemetry.io/build-tools/checkfile v0.10.0 h1:RjwCDirwXHFTGA3Nh6nL6P2x43abZFGiMEyk7GCQee4=
 go.opentelemetry.io/build-tools/checkfile v0.10.0/go.mod h1:hmR/xk4LQkhQx2hsIELlowjoc+zB/4dGUEcDnCyvKdo=
-go.opentelemetry.io/build-tools/chloggen v0.9.0 h1:sHdl6T5NTlGhRwy7du4APkd2GZEamI4DfBitdKlzxGU=
-go.opentelemetry.io/build-tools/chloggen v0.9.0/go.mod h1:zuYbAo3TkrHo3C7lCrM5dHWSS50BDr0UfRYtyBFv2dQ=
+go.opentelemetry.io/build-tools/chloggen v0.11.0 h1:PYbfjzw/4pHNfwH0kCAMolvmdorMVGxSSFY8A9097fw=
+go.opentelemetry.io/build-tools/chloggen v0.11.0/go.mod h1:zuYbAo3TkrHo3C7lCrM5dHWSS50BDr0UfRYtyBFv2dQ=
 go.opentelemetry.io/build-tools/crosslink v0.9.0 h1:LOeJzMxsxBG2qMKeO22fRs91QvDfY+BA5pF1skTjbx0=
 go.opentelemetry.io/build-tools/crosslink v0.9.0/go.mod h1:VaSi2ahs+r+v//m6OpqTkD5siSFVta9eTHhKqPsfH/Q=
 go.opentelemetry.io/build-tools/multimod v0.9.0 h1:Im9PCGhfmKQC2XR0aTYzADNiOZLk9QEQgibDhadH+i0=