diff --git a/docs/_docset.yml b/docs/_docset.yml index ac1f9c804..754fbf54c 100644 --- a/docs/_docset.yml +++ b/docs/_docset.yml @@ -165,6 +165,7 @@ toc: - file: changelog-add.md - file: changelog-bundle.md - file: changelog-bundle-amend.md + - file: changelog-gh-release.md - file: changelog-init.md - file: changelog-remove.md - file: changelog-render.md diff --git a/docs/cli/release/changelog-gh-release.md b/docs/cli/release/changelog-gh-release.md new file mode 100644 index 000000000..ae4ecdd08 --- /dev/null +++ b/docs/cli/release/changelog-gh-release.md @@ -0,0 +1,82 @@ +--- +navigation_title: "changelog gh-release" +--- + +# changelog gh-release + +Create changelog files and a bundle from a GitHub release by parsing pull request references in the release notes. + +For details and examples, go to [](/contribute/changelog.md). + +## Usage + +```sh +docs-builder changelog gh-release [version] [options...] [-h|--help] +``` + +## Arguments + +`repo` +: Required: GitHub repository in `owner/repo` format (for example, `elastic/elasticsearch`) or just the repository name (for example, `elasticsearch`), which defaults to `elastic` as the owner. + +`version` +: Optional: The release tag to fetch (for example, `v9.2.0` or `9.2.0`). Defaults to `latest`. + +## Options + +`--config ` +: Optional: Path to the changelog.yml configuration file. Defaults to `docs/changelog.yml`. + +`--output ` +: Optional: Output directory for the generated changelog files. Defaults to `./changelogs`. + +`--strip-title-prefix` +: Optional: Remove square brackets and the text within them from the beginning of pull request titles, and also remove a colon if it follows the closing bracket. +: For example, `"[Inference API] New embedding model support"` becomes `"New embedding model support"`. +: Multiple bracket prefixes are also supported (for example, `"[Discover][ESQL] Fix filtering"` becomes `"Fix filtering"`). + +`--warn-on-type-mismatch` +: Optional: Warn when the type inferred from Release Drafter section headers (for example, "Bug Fixes") doesn't match the type derived from the pull request's labels. Defaults to `true`. + +## Output + +The command creates two types of output in the directory specified by `--output`: + +- One YAML changelog file per pull request found in the release notes. +- A `changelog-bundle.yaml` file that references all created changelog files. + +The product, target version, and lifecycle are inferred automatically from the release tag and the repository name (via [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml)). For example, a tag of `v9.2.0` on `elastic/elasticsearch` creates changelogs with `product: elasticsearch`, `target: 9.2.0`, and `lifecycle: ga`. + +## Examples + +### Create changelogs from the latest release + +```sh +docs-builder changelog gh-release elastic/elasticsearch +``` + +### Create changelogs from a specific version tag + +```sh +docs-builder changelog gh-release elastic/elasticsearch v9.2.0 +``` + +### Use a short repository name + +```sh +docs-builder changelog gh-release elasticsearch v9.2.0 +``` + +### Specify a custom output directory + +```sh +docs-builder changelog gh-release elasticsearch v9.2.0 \ + --output ./docs/changelog \ + --config ./docs/changelog.yml +``` + +### Strip component prefixes from titles + +```sh +docs-builder changelog gh-release elasticsearch v9.2.0 --strip-title-prefix +``` diff --git a/docs/cli/release/index.md b/docs/cli/release/index.md index c681627ef..0aeb14348 100644 --- a/docs/cli/release/index.md +++ b/docs/cli/release/index.md @@ -8,6 +8,7 @@ These commands are associated with product release documentation. - [changelog add](changelog-add.md) - Create a changelog file - [changelog bundle](changelog-bundle.md) - Create a changelog bundle file +- [changelog gh-release](changelog-gh-release.md) - Create changelogs and a bundle from a GitHub release - [changelog init](changelog-init.md) - Initialize changelog configuration and folder structure - [changelog bundle-amend](changelog-bundle-amend.md) - Add entries to an existing bundle - [changelog render](changelog-render.md) - Generate markdown output from changelog bundle files diff --git a/docs/contribute/changelog.md b/docs/contribute/changelog.md index 7d3f4b434..04125248e 100644 --- a/docs/contribute/changelog.md +++ b/docs/contribute/changelog.md @@ -24,6 +24,7 @@ To use the `docs-builder changelog` commands in your development workflow: 1. Optional: Add labels to your GitHub pull requests to indicate that they are not notable and should not generate changelogs. For example, `non-issue` or `release_notes:skip`. Alternatively, you can assume that all PRs are *not* notable unless a specific label is present (for example, `@Public`). 1. [Configure changelog settings](#changelog-settings) to correctly interpret your PR labels. 1. [Create changelogs](#changelog-add) with the `docs-builder changelog add` command. + - Alternatively, use the `docs-builder changelog gh-release` command as a one-shot alternative that creates changelog files and a bundle directly from a GitHub release. Refer to [Create changelogs from a GitHub release](#changelog-gh-release). 1. [Create changelog bundles](#changelog-bundle) with the `docs-builder changelog bundle` command. For example, create a bundle for the pull requests that are included in a product release. 1. [Create documentation](#render-changelogs) with the `docs-builder changelog render` command. @@ -480,6 +481,26 @@ docs-builder changelog add \ This creates one changelog file for each PR specified, whether from files or directly. +## Create changelogs from a GitHub release [changelog-gh-release] + +If you use [Release Drafter](https://github.com/release-drafter/release-drafter) or a similar tool to generate GitHub release notes that reference pull requests, you can use the `docs-builder changelog gh-release` command as a one-shot alternative to `changelog add` + `changelog bundle`. +The command parses the release notes, creates one changelog file per pull request found, and creates a `changelog-bundle.yaml` file — all in a single step. + +For up-to-date command usage information, use the `-h` option or refer to [](/cli/release/changelog-gh-release.md). + +```sh +docs-builder changelog gh-release elasticsearch v9.2.0 \ + --output ./docs/changelog \ + --config ./docs/changelog.yml +``` + +The product, target version, and lifecycle are inferred automatically from the release tag and the repository name. +For example, a tag of `v9.2.0` on `elasticsearch` creates changelogs with `product: elasticsearch`, `target: 9.2.0`, and `lifecycle: ga`. + +:::{note} +This command requires a `GITHUB_TOKEN` or `GH_TOKEN` environment variable (or an active `gh` login) to fetch release details from the GitHub API. Refer to [Authorization](#authorization) for details. +::: + ## Create bundles [changelog-bundle] You can use the `docs-builder changelog bundle` command to create a YAML file that lists multiple changelogs. @@ -682,7 +703,10 @@ docs-builder changelog bundle --issues "12345,12346" \ ### Filter by pull request file [changelog-bundle-file] -If you have a file that lists pull requests (such as PRs associated with a GitHub release): +If you have a file that lists pull requests (such as PRs associated with a GitHub release), you can pass it to `--prs`. +If your release uses Release Drafter-style notes, you can also let the tool fetch and parse the PR list directly with `docs-builder changelog gh-release`. Refer to [Create changelogs from a GitHub release](#changelog-gh-release). + +If you have a file that lists pull requests: ```txt https://github.com/elastic/elasticsearch/pull/108875