changelog init: support all three onboarding paths and optionally scaffold workflow files

[theletterf]

`docs-builder changelog init` currently scaffolds a generic `changelog.yml` and the changelog directory. It doesn't account for the three distinct ways teams use the feature, and it never touches workflow files — leaving onboarding incomplete without manual steps.

Three paths

Mode	Per-PR entries	Automated bundle	Workflow trigger
`gh-release`	No	Yes (from GitHub release notes)	`on: release` or inline jobs
`changelog-auto`	Yes	Yes (at release time)	`on: release` or inline jobs
`changelog-manual`	Yes	No (manual `changelog bundle`)	push + PR only

Proposed changes

1. Mode selection

Accept `--mode <gh-release|changelog-auto|changelog-manual>`. When omitted and stdin is a TTY, prompt interactively:

```
? How are release notes generated?

From GitHub release notes at publish time (gh-release)
Per-PR changelog entries, bundled automatically at release (changelog-auto)
Per-PR changelog entries, bundled manually (changelog-manual)
```

2. Path-appropriate `changelog.yml` skeleton

• `gh-release`: emit only the `bundle:` section. Omit `pivot:`, `rules:`, and `profiles:` — unused by this path.
• `changelog-auto` / `changelog-manual`: full skeleton with `pivot.types` (placeholders for `feature`, `bug-fix`, `breaking-change`), `rules.create.exclude`, and `rules.bundle.exclude_types: "other"` (required: release-drafter headers for Maintenance/Chore/Automation/CI/Redesign all map to `other` in the parser).

3. Optional workflow file generation (`--workflows` flag or prompted)

Write the three callers under `.github/workflows/`:

• `release-notes.yml`
• `release-notes-comments.yml`
• `release-notes-changelog-file.yml`

`gh-release` and `changelog-auto`: add `on: release: [published]` and `bundle-on-release: true`. Also emit a warning:

```
⚠ bundle-on-release: true only fires when the release is published by a human or a
non-GITHUB_TOKEN. If your release workflow uses `github.token`, add the bundle jobs
inline instead.
```

`changelog-manual`: `release-notes.yml` gets only `pull_request` and `push` triggers.

Do not overwrite existing workflow files; skip with a warning if present.

4. Fixture entry warning

After writing the changelog directory, scan for existing `*.yaml` files. If found:

```
⚠ Found N existing .yaml files in docs/changelog/.
Only files directly in this directory are uploaded (TopDirectoryOnly).
Move demo/sample/fixture entries to docs/changelog/examples/ before the first push to main.
```

Out of scope

• Detecting the release token type automatically (not reliably possible from the repo alone).
• Modifying the release workflow to add inline bundle jobs (covered by the warning above).
• Writing `release-notes-backfill.yml` (follow-up).

Acceptance criteria

• `--mode gh-release` produces a minimal `changelog.yml` with no `pivot:` or `rules:`.
• `--mode changelog-auto --workflows` writes all three workflow files and prints the GITHUB_TOKEN warning.
• `--mode changelog-manual --workflows` writes workflow files with no `release:` trigger.
• Running without `--mode` on a TTY prompts for the path.
• Existing files are never silently overwritten.
• Fixture warning fires when `*.yaml` files are found in the target directory.

[lcawl]

gh-release: emit only the bundle: section. Omit pivot:, rules:, and profiles: — unused by this path.

I don't know the docs-builder changelog gh-release command very well but I think it does use some pivot and rules settings.

NOTE: The subsequent info predates #4178 so take it with a handful of salt...

Here's a quick AI analysis of where/how the gh-release command was using config settings:

gh-release still uses pivot and rules

...The claim in elastic/docs-builder#4151 that gh-release should emit only bundle: and omit pivot:, rules:, and profiles: because they are unused is incorrect for pivot and rules. profiles is unused by the changelog gh-release command, but it is used by a different GitHub-release bundling path.

What changelog gh-release actually does

/docs-builder/src/services/Elastic.Changelog/GithubRelease/GitHubReleaseChangelogService.cs (current docs-builder):

1. Loads changelog.yml.
2. Resolves PRs from the previous tag → current tag commit range (not from release-body section headers).
3. For each PR: checked-in CDN pool entry wins; otherwise synthesizes an entry from PR metadata.
4. Bundles the created files via ChangelogBundlingService (option-mode, not a named profile).

flowchart TD
  release[GitHub release tag]
  range[Commit range previousTag to currentTag]
  pool{CDN pool entry exists?}
  pivot[Map PR labels via pivot.types and pivot.areas]
  createRules[Skip via rules.create]
  synth[Write synthesized YAML]
  verbatim[Write pool YAML verbatim]
  bundle[changelog bundle path applies rules.bundle]
  release --> range --> pool
  pool -->|yes| verbatim --> bundle
  pool -->|no| createRules
  createRules -->|excluded| skip[Omit PR]
  createRules -->|keep| pivot --> synth --> bundle

Loading

pivot: is used

Inverted pivot.types becomes config.LabelToType in docs-builder/src/Elastic.Documentation.Configuration/Changelog/ChangelogConfigurationLoader.cs. Synthesis maps PR labels to type (and areas) here:

		// Derive type and areas from labels
		if (config.LabelToType != null && config.LabelToType.Count > 0)
			labelDerivedType = MapLabelsToType(prInfo.Labels.ToArray(), config.LabelToType);
		// ...
		var finalTypeString = labelDerivedType ?? ChangelogEntryType.Other.ToStringFast(true);

If pivot.types is omitted, every synthesized entry becomes type: other unless a pool file already exists. That is why docs-builder's own docs/changelog.yml still defines pivot.types and rules.bundle.exclude_types: "other": unmapped maintenance labels land on other and are dropped at bundle time.

The issue's note that Release Drafter headers map to other is about src/services/Elastic.Changelog/GitHub/ReleaseNoteParser.cs. That parser is still used for option-mode --release-version / profile source: github_release PR lists. The changelog gh-release command now types from PR labels + pivot.types, not from those headers. Comments in docs-builder's changelog.yml about section headers are slightly behind that rewrite.

rules: is used

• rules.create: ShouldSkipPrDueToLabelBlockers skips PRs with exclude/include labels before synthesis (not applied to verbatim pool entries).
• rules.bundle: documented as applying to both changelog bundle and changelog gh-release in configure-ref.md and cmd-gh-release.md. The gh-release command calls BundleChangelogs, which runs the bundle secondary filter.

A skeleton that omits rules would still run, but you would lose skip-labels at synthesis time and type/product/area filtering at bundle time.

profiles: is unused by this command, used by a sibling path

changelog gh-release does not read bundle.profiles. It writes {version}-{product}-bundle.yml under a bundles/ subfolder of the output dir.

GitHub-release filtering can still be a profile:

bundle:
  profiles:
    agent-gh-release:
      source: github_release

That is changelog bundle <profile> <tag>, not changelog gh-release. --plan even treats "no bundle.profiles" as the signal to set Actions output mode=gh-release. If init later writes example profiles, that auto-detection breaks until the caller passes a profile name.

So: omitting profiles is reasonable only for repos that will call changelog gh-release / the docs-actions gh-release workflow. It is not true that GitHub-release bundling never uses profiles.

changelog gh-release never read bundle.profiles. There is no removal PR.

• Introduced in elastic/docs-builder#2526 (6df23e7c3): one-shot create+bundle, product inferred from products.yml via GetProductByRepositoryName (single match; ambiguous/missing → error).
• GitHub-release profiles landed on changelog bundle / changelog remove, not on gh-release: elastic/docs-builder#2843 (source: github_release and --release-version).
• elastic/docs-builder#4022 did not drop profiles. It switched gh-release from the single-product lookup to GetProductsByRepositoryName and products[0] so multi-product repos like elastic/cloud no longer fail. That is when first-product-wins started.

I also dug into whether this meant the gh-release path could only support repos that do releases for a single product... which resulted in a very complex discussion that I'm hoping is addressed by #4178 and so will omit here.

Based on the information at the time I generated the analysis, it recommended to correct the proposed gh-release skeleton to still include:

• pivot.types (and areas/products if the repo uses those labels)
• rules.create.exclude if they skip labels at synthesis or share the file with PR validation
• rules.bundle (typically exclude_types: other when unmapped labels should not ship)
• bundle: directories / owner / repo
• profiles only if they will use changelog bundle with source: github_release (or other named profiles)