diff --git a/.chloggen/TEMPLATE.yaml b/.chloggen/TEMPLATE.yaml index 56964f93f07..5f4d66bd650 100644 --- a/.chloggen/TEMPLATE.yaml +++ b/.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: [] \ No newline at end of file diff --git a/.chloggen/chloggen-config.yaml b/.chloggen/chloggen-config.yaml new file mode 100755 index 00000000000..db25d25bd25 --- /dev/null +++ b/.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] diff --git a/.chloggen/config.yaml b/.chloggen/config.yaml new file mode 100644 index 00000000000..19a2957bd25 --- /dev/null +++ b/.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] diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml index ee03803e01f..28261d79f1f 100644 --- a/.github/workflows/changelog.yml +++ b/.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) diff --git a/CHANGELOG-API.md b/CHANGELOG-API.md new file mode 100644 index 00000000000..237c3a656ec --- /dev/null +++ b/CHANGELOG-API.md @@ -0,0 +1,8 @@ + + +# Go API Changelog + +This changelog includes only developer-facing changes. +If you are looking for user-facing changes, check out [CHANGELOG.md](./CHANGELOG.md). + + diff --git a/CHANGELOG.md b/CHANGELOG.md index f8901d7dd20..0be183a67d0 100644 --- a/CHANGELOG.md +++ b/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). + ## v1.0.0-rcv0014/v0.82.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e278f377abc..7e723082cee 100644 --- a/CONTRIBUTING.md +++ b/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`) diff --git a/Makefile b/Makefile index 5d969d45131..1900c26c44b 100644 --- a/Makefile +++ b/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) diff --git a/Makefile.Common b/Makefile.Common index 5fd4616989c..a5807ab84c3 100644 --- a/Makefile.Common +++ b/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 diff --git a/internal/tools/go.mod b/internal/tools/go.mod index c67a9a2fa56..db2822748a8 100644 --- a/internal/tools/go.mod +++ b/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 diff --git a/internal/tools/go.sum b/internal/tools/go.sum index e3447f93616..ad4373d56c0 100644 --- a/internal/tools/go.sum +++ b/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=