Add support for using the OpenTelemetry chloggen tool (#923)

.chloggen/TEMPLATE.yaml

@@ -0,0 +1,12 @@
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type:
+# The name of the component, or a single word describing the area of concern, (e.g. agent, clusterReceiver, gateway, networkExplorer, operator, chart, other)
+component:
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note:
+# One or more tracking issues related to the change
+issues: []
+# (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:

.chloggen/migrate-to-otel-by-default.yaml

@@ -0,0 +1,12 @@
+# 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. agent, clusterReceiver, gateway, networkExplorer, operator, chart, other)
+component: agent
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Change the default logs collection engine (`logsEngine`) to the native OpenTelemetry logs collection (`otel`)
+# One or more tracking issues related to the change
+issues: [934]
+# (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 you want to keep using Fluentd sidecar for the logs collection, set `logsEngine' to 'fluentd` in your values.yaml

.chloggen/otl-add-chloggen.yaml

@@ -0,0 +1,12 @@
+# 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. agent, clusterReceiver, gateway, networkExplorer, operator, chart, other)
+component: chart
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add support for OpenTelemetry CHANGELOG.md generator tool, see [chloggen](https://github.com/open-telemetry/opentelemetry-operator/tree/main/.chloggen)
+# One or more tracking issues related to the change
+issues: [923]
+# (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:

.github/workflows/validate-changelog.yaml

@@ -1,22 +1,38 @@
 name: Ensure valid and up-to-date Changelog
 
+# Description: Automates the validation of .chloggen (CHANGELOG.md) entries ensuring:
+#   1. All entries are valid.
+#   2. A new entry is added for updates to chart templates or rendered example content.
+#   3. Bypass validation with a 'Skip Changelog' label or a PR title containing '[chore]'.
+
 on: pull_request
 
 jobs:
   validate-changelog:
+    if: ${{ !contains(github.event.pull_request.labels.*.name, 'Skip Changelog') && !contains(github.event.pull_request.title, '[chore]') }}
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
-      - name: Lint changelog file
-        uses: avto-dev/markdown-lint@v1
-        with:
-          rules: /lint/rules/changelog.js
-          config: /lint/config/changelog.yml
-          args: ./CHANGELOG.md
+      - name: Set up Go
+        uses: actions/setup-go@v4
+
+      - name: Install chloggen
+        run: make install-tools
+
+      - name: Run make chlog-validate
+        run: |
+          if ! make chlog-validate; then
+            echo "Options:"
+            echo "- Add a Changelog Entry: Please add a '.yaml' file to the './.chloggen/' directory detailing the changes in your commit. See 'CONTRIBUTING.md' for guidance on creating this entry."
+            echo "- Skip the Changelog Check: If your changes don't necessitate a changelog entry or it's a minor chore, you can skip this check by:"
+            echo "  1. Adding '[chore]' to the title of the pull request"
+            echo "  2. Applying the 'Skip Changelog' label to the pull request."
+            exit 1
+          fi
 
       - name: Read current version of the Chart
         id: read-chart

CONTRIBUTING.md

@@ -61,16 +61,45 @@ To send us a pull request, please:
    reformat all the code, it will be hard for us to focus on your change.
 3. Please follow the versioning instructions found in the [RELEASE.md](https://github.com/signalfx/splunk-otel-collector-chart/blob/main/RELEASE.md).
 4. Ensure local tests pass and add new tests related to the contribution.
-5. Commit to your fork using clear commit messages.
-6. Send us a pull request, answering any default questions in the pull request
+5. Add a CHANGELOG.md entry (make chlog-new) if the behavior of this chart is altered, see [Changelog Guidelines](https://signalfx/splunk-otel-collector-chart/blob/main/CONTRIBUTING.md#changelog-guidelines).
+6. Render example documentation (make render) if chart templates are updated.
+7. Commit to your fork using clear commit messages.
+8. Send us a pull request, answering any default questions in the pull request
    interface.
-7. Pay attention to any automated CI failures reported in the pull request, and
+9. Pay attention to any automated CI failures reported in the pull request, and
    stay involved in the conversation.
 
 GitHub provides additional documentation on [forking a
 repository](https://help.github.com/articles/fork-a-repo/) and [creating a pull
 request](https://help.github.com/articles/creating-a-pull-request/).
 
+## Changelog Guidelines
+
+### When to Add an Entry
+
+Include a changelog entry for pull requests affecting:
+
+1. Collector configuration or behavior
+2. Telemetry data output
+
+**Exceptions:**
+
+- Documentation-only changes
+- Minor, non-impactful updates (e.g., code cleanup)
+
+### Adding an Entry
+
+**Quick Guide:**
+
+1. **Create File:** Run `make chlog-new` to generate a `.yaml` in `./.chloggen`.
+2. **Edit File:** Update the `.yaml` with relevant info.
+3. **Validate:** Use `make chlog-validate` to check format.
+4. **Commit:** Add the `.yaml` to your pull request.
+
+**Manual Option:**
+
+- Copy `./.chloggen/TEMPLATE.yaml` or create a unique `.yaml` file.
+
 ## Finding contributions to work on
 
 Looking at the existing issues is a great way to find something to contribute

Makefile

@@ -1,25 +1,97 @@
-.PHONY: render
-render: repo-update dep-build
-	bash ./examples/render-examples.sh
+##@ General
+# The general settings and variables for the project
+SHELL := /bin/bash
+
+# TODO: Move CHART_FILE_PATH and VALUES_FILE_PATH here, currently set in multiple places
+# The version of the splunk-otel-collector chart
+VERSION := $(shell grep "^version:" helm-charts/splunk-otel-collector/Chart.yaml | awk '{print $$2}')
+
+## Location for GO resources
+ifeq (,$(shell go env GOBIN))
+GOBIN=$(shell go env GOPATH)/bin
+else
+GOBIN=$(shell go env GOBIN)
+endif
+
+## Location to install dependencies to
+LOCALBIN ?= $(shell pwd)/bin
+$(LOCALBIN):
+	mkdir -p $(LOCALBIN)
+CHLOGGEN ?= $(LOCALBIN)/chloggen
+
+# The help target as provided
+.PHONY: help
+help: ## Display Makefile help information for all actions
+	@awk 'BEGIN {FS = ":.*##"; \
+                 printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} \
+          /^[a-zA-Z_0-9-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } \
+          /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) }' \
+          $(MAKEFILE_LIST)
+
+##@ Initialization
+# Tasks for setting up the project environment
+
+.PHONY: install-tools
+install-tools: ## Install tools (macOS/Linux)
+	LOCALBIN=$(LOCALBIN) GOBIN=$(LOCALBIN) ci_scripts/install-tools.sh || exit 1
+
+##@ Build
+# Tasks related to building the Helm chart
 
 .PHONY: repo-update
-repo-update:
+repo-update: ## Update Helm repositories to latest
 	@{ \
 	if ! (helm repo list | grep -q open-telemetry) ; then \
-		helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts ;\
+		helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts || exit 1; \
 	fi ;\
 	if ! (helm repo list | grep -q jetstack) ; then \
-		helm repo add jetstack https://charts.jetstack.io ;\
+		helm repo add jetstack https://charts.jetstack.io || exit 1; \
 	fi ;\
-	helm repo update open-telemetry jetstack ;\
+	helm repo update open-telemetry jetstack || exit 1; \
 	}
 
 .PHONY: dep-build
-dep-build:
+dep-build: ## Build the Helm chart with latest dependencies from the current Helm repositories
 	@{ \
-  OK=true ;\
-  DIR=helm-charts/splunk-otel-collector ;\
-	if ! helm dependencies list $$DIR | grep open-telemetry | grep -q ok ; then OK=false ; fi ;\
-	if ! helm dependencies list $$DIR | grep jetstack | grep -q ok ; then OK=false ; fi ;\
-	if ! $$OK ; then helm dependencies build $$DIR ; fi ;\
+	DEP_OK=true ;\
+	DIR=helm-charts/splunk-otel-collector ;\
+	if ! helm dependencies list $$DIR | grep open-telemetry | grep -q ok ; then DEP_OK=false ; fi ;\
+	if ! helm dependencies list $$DIR | grep jetstack | grep -q ok ; then DEP_OK=false ; fi ;\
+	if [ "$$DEP_OK" = "false" ] ; then helm dependencies build $$DIR || exit 1; fi ;\
 	}
+
+.PHONY: render
+render: repo-update dep-build ## Render the Helm chart with the examples as input
+	examples/render-examples.sh || exit 1
+
+##@ Changelog
+# Tasks related to changelog management
+
+.PHONY: chlog-available
+chlog-available: ## Validate the chloggen tool is available
+	@if [ -z "$(CHLOGGEN)" ]; then \
+		echo "Error: chloggen is not available. Please run 'make install-tools' to install it."; \
+		exit 1; \
+	fi
+
+# Example Usage:
+# 	make chlog-new CHANGE_TYPE=enhancement COMPONENT=agent NOTE="Add X" ISSUES='[42]'
+# 	make chlog-new [CHANGE_TYPE=enhancement] [COMPONENT=agent] [NOTE="Add X"] [ISSUES='[42]'] [FILENAME=add-x] [SUBTEXT="Add Y"]
+.PHONY: chlog-new
+chlog-new: chlog-available ## Creates or updates a YAML file under .chloggen
+	ci_scripts/chloggen-new.sh || exit 1
+
+.PHONY: chlog-validate
+chlog-validate: chlog-available ## Validates changelog requirements for pull requests
+	$(CHLOGGEN) validate || exit 1
+	ci_scripts/chloggen-pr-validate.sh || exit 1
+
+.PHONY: chlog-preview
+chlog-preview: chlog-validate ## Provide a preview of the generated CHANGELOG.md file for a release
+	$(CHLOGGEN) update --dry || exit 1
+
+# Example Usage: make chlog-update
+.PHONY: chlog-update
+chlog-update: chlog-validate ## Creates an update to CHANGELOG.md for a release entry from content in .chloggen
+	$(CHLOGGEN) update --version "[$(VERSION)] - $$(date +'%Y-%m-%d')" || exit 1; \
+	ci_scripts/chloggen-update.sh || exit 1

RELEASE.md

@@ -16,6 +16,7 @@ of `version` field.
 To make a new release of the helm chart:
 1. Bump the chart `version` in [Chart.yaml](helm-charts/splunk-otel-collector/Chart.yaml)
 1. Run `make render` to update Helm dependencies and render all the examples with the latest changes.
+1. Run `make chlog-update` to update CHANGELOG.md for the release.
 1. Create PR and request review from the team.
 1. When the PR gets merged, the release will automatically be made and the helm repo updated.
 1. Release notes are not populated automatically. So make sure to update them manually using the notes from [CHANGELOG](./CHANGELOG.md).

ci_scripts/chloggen-new.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+# Purpose: Automates the creation or update of changelog entries based on input parameters.
+# Notes:
+#   - Should be executed via the `make chlog-new` command.
+#   - Facilitates the automation of changelog entry creation.
+#   - Intended to be used with the `make chlog-new` command.
+#
+# Optional Parameters:
+#   - CHANGE_TYPE: Type of change (e.g., 'enhancement', 'bug_fix')
+#   - COMPONENT: Component affected by the change (e.g., 'operator')
+#   - NOTE: Brief description of the change
+#   - ISSUES: List of related issues or PRs
+#   - SUBCONTEXT: Additional information for the changelog entry
+#   - FILENAME: Name of the file to create or update, defaults to git branch name
+#   - DEBUG_MODE: Can be enabled for debugging
+
+# Include the base utility functions for setting and debugging variables
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+source "$SCRIPT_DIR/base_util.sh"
+
+# ---- Initialize Variables ----
+if [[ -z "$FILENAME" ]]; then
+  setd "FILENAME" $(git branch --show-current | tr -d '[:space:][:punct:]')
+fi
+
+# ---- Changelog Entry Validation ----
+# Check for the existence of TEMPLATE.yaml
+if [ ! -f ".chloggen/TEMPLATE.yaml" ]; then
+  echo "Error: .chloggen/TEMPLATE.yaml not found. Ensure it exists."
+  exit 1
+fi
+
+# ---- Changelog Entry Update ----
+# Check if a changelog entry with the given filename already exists
+if [ -f ".chloggen/${FILENAME}.yaml" ]; then
+  echo "Changelog entry ${FILENAME}.yaml already exists. Updating."
+else
+  echo "Creating new changelog entry ${FILENAME}.yaml."
+  cp .chloggen/TEMPLATE.yaml .chloggen/${FILENAME}.yaml
+fi
+
+# Update fields only if the argument was passed
+[[ ! -z "$CHANGE_TYPE" ]] && yq eval -i ".change_type = \"$CHANGE_TYPE\"" .chloggen/${FILENAME}.yaml
+[[ ! -z "$COMPONENT" ]] && yq eval -i ".component = \"$COMPONENT\"" .chloggen/${FILENAME}.yaml
+[[ ! -z "$NOTE" ]] && yq eval -i ".note = \"$NOTE\"" .chloggen/${FILENAME}.yaml
+[[ ! -z "$SUBTEXT" ]] && yq eval -i ".subtext = \"$SUBTEXT\"" .chloggen/${FILENAME}.yaml
+# Extend the list of issue IDs rather than overwriting them
+if [ ! -z "$ISSUES" ]; then
+  # Extend the .issues field and update it
+  setd "OLD_ISSUES" "$(yq eval '.issues' ".chloggen/${FILENAME}.yaml")"
+  # Combine the old and new issues and deduplicate them
+  setd "NEW_ISSUES" "'$(echo "$OLD_ISSUES" "$ISSUES" | jq -sc 'add | unique')'"
+  echo "Resulting issues: $NEW_ISSUES"
+  yq eval -i ".issues = ${NEW_ISSUES//\'/} | .issues style=\"flow\" " ".chloggen/${FILENAME}.yaml"
+fi
+
+
+echo "${FILENAME}.yaml has been created or updated."
+exit 0

ci_scripts/chloggen-pr-validate.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# Purpose: Validates the presence of a changelog entry based on file changes.
+# Notes:
+#   - Should be executed via the `make chlog-validate` command.
+#   - Designed to be a local or CI/CD pipeline check.
+#   - Checks for changes in specific directories and files:
+#       1. Helm chart templates in 'helm-charts/splunk-otel-collector/templates/*'
+#       2. Rendered manifests in 'examples/*/rendered_manifests/*'
+#   - Requires a '.chloggen' file if any of the above conditions is met.
+
+# Include the base utility functions for setting and debugging variables
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+source "$SCRIPT_DIR/base_util.sh"
+
+# ---- Git Fetch Main ----
+if ! git show-ref --verify --quiet refs/heads/main; then
+  echo "The main branch is not available. Fetching..."
+  git fetch origin main:main
+fi
+
+# ---- Initialize Variables ----
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+LAST_COMMON_COMMIT=$(git merge-base $CURRENT_BRANCH main)
+HELM_CHART_UPDATED=0
+RENDERED_MANIFESTS_UPDATED=0
+CHLOGGEN_FILE_PRESENT=0
+
+# Get a list of all changed files since the last common commit with main
+CHANGED_FILES=$(git diff --name-only $LAST_COMMON_COMMIT HEAD)
+# Include uncommitted changes
+UNCOMMITTED_CHANGED_FILES=$(git diff --name-only)
+
+# Check if either COMMITTED_CHANGED_FILES or UNCOMMITTED_CHANGED_FILES is non-empty
+if [[ -n "$UNCOMMITTED_CHANGED_FILES" ]]; then
+    CHANGED_FILES="$CHANGED_FILES $UNCOMMITTED_CHANGED_FILES"
+fi
+
+# ---- File Change Analysis ----
+for file in $CHANGED_FILES; do
+  case "$file" in
+    helm-charts/*/templates*)
+        HELM_CHART_UPDATED=1
+        ;;
+    examples/*/rendered_manifests*)
+        RENDERED_MANIFESTS_UPDATED=1
+        ;;
+    .chloggen*)
+        CHLOGGEN_FILE_PRESENT=1
+        ;;
+  esac
+done
+
+# ---- Changelog Entry Validation ----
+if { [[ $HELM_CHART_UPDATED -eq 1 ]] || [[ $RENDERED_MANIFESTS_UPDATED -eq 1 ]]; } && [[ $CHLOGGEN_FILE_PRESENT -eq 0 ]]; then
+    printf "Changed Files:\n${CHANGED_FILES}\n"
+    echo "FAIL: A changelog entry (.chloggen) is required for this commit due to:"
+    [[ $HELM_CHART_UPDATED -eq 1 ]] && echo "- Updates to files under 'helm-charts/*/templates*'"
+    [[ $RENDERED_MANIFESTS_UPDATED -eq 1 ]] && echo "- Updates to files under 'examples/*/rendered_manifests*'"
+    exit 1
+fi
+
+echo "PASS: all changelog entries required for PR are valid"
+exit 0