diff --git a/.chloggen/TEMPLATE.yaml b/.chloggen/TEMPLATE.yaml index fe8b3830f9bc..0b2707a944f2 100644 --- a/.chloggen/TEMPLATE.yaml +++ b/.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: [] diff --git a/.chloggen/chloggen-config.yaml b/.chloggen/chloggen-config.yaml new file mode 100755 index 000000000000..73901e35f08f --- /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: [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] diff --git a/.chloggen/config.yaml b/.chloggen/config.yaml new file mode 100644 index 000000000000..19a2957bd252 --- /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/.chloggen/heartbeat-while-startup.yaml b/.chloggen/heartbeat-while-startup.yaml index 8c41c25735dd..8ca5accc6f0c 100644 --- a/.chloggen/heartbeat-while-startup.yaml +++ b/.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] diff --git a/.chloggen/k8sclusterreceiver-enable-disable-metrics.yaml b/.chloggen/k8sclusterreceiver-enable-disable-metrics.yaml index fb155f4b3fcd..f33381ebe9a0 100755 --- a/.chloggen/k8sclusterreceiver-enable-disable-metrics.yaml +++ b/.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] diff --git a/.chloggen/mdatagen-avoid-reusing-resource-builder.yaml b/.chloggen/mdatagen-avoid-reusing-resource-builder.yaml index 9bf68a849bd8..6954b736f197 100755 --- a/.chloggen/mdatagen-avoid-reusing-resource-builder.yaml +++ b/.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] diff --git a/.chloggen/splunkhecreceiver-align-success-response.yaml b/.chloggen/splunkhecreceiver-align-success-response.yaml index 2f0358d9bf92..6aec7acb7c40 100644 --- a/.chloggen/splunkhecreceiver-align-success-response.yaml +++ b/.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] diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml index 0481fc9a12fc..8a7fdfd910ee 100644 --- a/.github/workflows/changelog.yml +++ b/.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) diff --git a/CHANGELOG-API.md b/CHANGELOG-API.md new file mode 100644 index 000000000000..e9bf06bff19c --- /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 50ee5fa56993..36364ebad069 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). + ## v0.82.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3ac295c54950..1a6857390db9 100644 --- a/CONTRIBUTING.md +++ b/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`) diff --git a/Makefile b/Makefile index e6ce946a5e02..a443dd0fd479 100644 --- a/Makefile +++ b/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) diff --git a/Makefile.Common b/Makefile.Common index d5787eea4f26..2d30511e8028 100644 --- a/Makefile.Common +++ b/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) diff --git a/internal/tools/go.mod b/internal/tools/go.mod index 1e694c3f0e68..2b4c77c329d9 100644 --- a/internal/tools/go.mod +++ b/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 diff --git a/internal/tools/go.sum b/internal/tools/go.sum index b426a0bc6764..904cf68ba4e6 100644 --- a/internal/tools/go.sum +++ b/internal/tools/go.sum @@ -741,8 +741,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/issuegenerator v0.9.0 h1:40Eiw3dYSmaTsY77H9FelAJELlDqyQuZOJtwyQxM4p8=