Generate separate changelog for end users and Go API consumers

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]

CHANGELOG-API.md

@@ -0,0 +1,5 @@
+<!-- This file is autogenerated. See CONTRIBUTING.md for instructions to add an entry. -->
+
+# Go API Changelog
+
+<!-- next version -->

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
 CHECKDOC     := $(TOOLS_BIN_DIR)/checkdoc
-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/checkdoc v0.9.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.9.0 h1:P6WstNx1gmj3bMFJFrJThuxFQlKztxOSCPR/2h
 go.opentelemetry.io/build-tools v0.9.0/go.mod h1:ZoM+TLPhEhTi09/nI9YKPlU563ocHoWrQXD994N5dMc=
 go.opentelemetry.io/build-tools/checkdoc v0.9.0 h1:Jk0MggS4gUJrRlq4XKSV4hmIyDU/TwQJyCy4GrXzMqM=
 go.opentelemetry.io/build-tools/checkdoc v0.9.0/go.mod h1:3dQZFtq1x9RrKDM3RWGo1BQjZxH67zUrKmsjLegWttc=
-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=