feat: new-features automated documentation

[Joibel]

Fixes #14155

Motivation

I don't enjoy doing minor/major releases because of the documentation mangling - so instead get PR authors to write it up as we go.

Modifications

Added a tool written in go to hack/featuregen to do what I thought needed doing.

The tests and documentation cover how it works, so I'm not going to repeat that here.

I decided against chloggen when it wasn't flexible enough for our process.

Verification

Silly number of mostly AI generated unit tests, where I checked their output.

Added a feature note here for this feature, so I'll find out if pr.yaml github workflow does the right thing.

Documentation

Added documentation to running-locally.md for how to use the tool as a developer.
Added documentation to releasing.md for the release manager.

[Copilot]

Pull Request Overview

Introduces an automated feature documentation generator in Go, along with tests, docs updates, Makefile targets, and CI workflow integration to streamline new-feature releases.

• Adds a CLI tool (featuregen) under hack/featuregen for creating, validating, previewing, and publishing feature docs
• Updates Makefile, GitHub Actions workflows, and project docs (running-locally.md, releasing.md) to incorporate the new tool
• Includes unit tests for parsing/formatting logic and CLI commands, plus a pending feature example in .features

Reviewed Changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
hack/featuregen/main.go	Implements CLI commands (new, validate, update)
hack/featuregen/contents.go	Parses metadata, validates headers/order, and formats feature output
hack/featuregen/components.go	Lists and validates allowed feature components
hack/featuregen/main_test.go	Tests for CLI behaviors and file operations
hack/featuregen/contents_test.go	Tests for parseContent and format logic
docs/running-locally.md	Developer instructions on generating and validating feature docs
docs/releasing.md	Release manager steps for updating and publishing feature docs
Makefile	New feature-new, features-validate, features-preview, etc. targets
.github/workflows/pr.yaml	PR-time checks to enforce feature-file additions and link validation
.github/workflows/ci-build.yaml	Expanded lint rules to include .features and hack/featuregen files
.features/pending/feat-notes.md	Example pending feature note
.features/TEMPLATE.md	Template file for new feature descriptions

[Copilot]

The expected value in the error message is incorrect. It should read "UI" instead of "Valid Component" to match the assertion condition.

Suggested change

	t.Errorf("loadFeatureFile() component = %v, want %v", data.Component, "Valid Component")
	t.Errorf("loadFeatureFile() component = %v, want %v", data.Component, "UI")

[Copilot]

[nitpick] Prepending a static # New features header before calling format, which itself emits an H1 for 'Unreleased' or the version, leads to duplicate top-level headers. Consider removing the extra # New features prefix and relying on format to render the correct H1.

Suggested change

	outputContent := "# New features\n\nThis is a concise list of new features.\n\n" + format(version, features)
	outputContent := format(version, features)

[Copilot]

[nitpick] The function builds up a large string via repeated + concatenation in loops. Using a strings.Builder would improve performance and reduce memory allocations for assembling the markdown output.

[Copilot]

Pull Request Overview

This PR introduces an automated feature documentation tool written in Go that allows developers to create, validate, preview, and update feature description files as part of the release process. Key changes include:

• Adding the "featuregen" tool and its tests in the hack/featuregen directory.
• Updating documentation in docs/running-locally.md and docs/releasing.md with instructions on creating and managing feature files.
• Enhancing build and workflow configurations (Makefile, GitHub Actions) to integrate feature file validation and processing.

Reviewed Changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
hack/featuregen/main.go	New CLI commands for feature creation, updating, and validating.
hack/featuregen/main_test.go	Unit tests for the new tool demonstrating file creation and errors.
hack/featuregen/contents.go	Functions to parse and format feature files with metadata.
hack/featuregen/contents_test.go	Tests for metadata extraction, ordering, and formatting.
hack/featuregen/components.go	Lists and validates allowed feature components.
docs/running-locally.md, docs/releasing.md	Updated documentation covering new feature workflows.
Makefile, GitHub Actions workflows	Added targets and steps for handling feature documentation.
.features directory	Adds a template and a sample pending feature document.

Comments suppressed due to low confidence (1)

.github/workflows/pr.yaml:42

• [nitpick] The shell condition used to check for added feature description files is complex; consider simplifying it or adding inline comments to clarify its intent and improve long-term maintainability.

if [[ 1 -gt $(git diff --diff-filter=A --name-only $(git merge-base origin/${{ github.base_ref }} $PR_HEAD) $PR_HEAD ./.features | grep -c \.md) ]]

[tico24]

Approved from a docs perspective.