diff --git a/docs/_docset.yml b/docs/_docset.yml index fd757a739..dd9d26547 100644 --- a/docs/_docset.yml +++ b/docs/_docset.yml @@ -42,6 +42,7 @@ toc: - file: branching-strategy.md - file: add-repo.md - file: release-new-version.md + - file: changelog.md - hidden: locally.md - hidden: on-the-web.md - folder: building-blocks @@ -152,6 +153,10 @@ toc: - file: inbound-links-validate.md - file: inbound-links-validate-all.md - file: inbound-links-validate-link-reference.md + - folder: release + children: + - file: index.md + - file: changelog-add.md - folder: migration children: - file: index.md diff --git a/docs/cli/index.md b/docs/cli/index.md index f9d9410a3..defe1d465 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -5,11 +5,12 @@ navigation_title: CLI (docs-builder) # Command line interface `docs-builder` is the binary used to invoke various commands. -These commands can be roughly grouped into three main categories +These commands can be roughly grouped into four main categories - [Documentation Set commands](#documentation-set-commands) - [Link commands](#link-commands) - [Assembler commands](#assembler-commands) +- [Release doc commands](#release-doc-commands) ### Global options @@ -22,7 +23,7 @@ The following options are available for all commands: : Explicitly set the configuration source one of `local`, `remote` or `embedded`. Defaults to `local` if available other wise `embedded` -## Documentation Set Commands +## Documentation set commands Commands that operate over a single documentation set. @@ -32,7 +33,7 @@ These commands are typically what you interface with when you are working on the [See available CLI commands for documentation sets](docset/index.md) -## Link Commands +## Link commands Outbound links, those going from the documentation set to other sources, are validated as part of the build process. @@ -40,8 +41,14 @@ Inbound links, those going from other sources to the documentation set, are vali [See available CLI commands for inbound links](links/index.md) -## Assembler Commands +## Assembler commands Assembler builds bring together all isolated documentation set builds and turn them into the overall documentation that gets published. [See available CLI commands for assembler](assembler/index.md) + +## Release doc commands + +Commands that pertain to creating and publishing product release documentation. + +[See available CLI commands for release docs](release/index.md) diff --git a/docs/cli/release/changelog-add.md b/docs/cli/release/changelog-add.md new file mode 100644 index 000000000..971e29bfd --- /dev/null +++ b/docs/cli/release/changelog-add.md @@ -0,0 +1,58 @@ +# changelog add + +Create a changelog file that describes a single item in the release documentation. +For details and examples, go to [](/contribute/changelog.md). + +## Usage + +```sh +docs-builder changelog add [options...] [-h|--help] +``` + +## Options + +`--action ` +: Optional: What users must do to mitigate. + +`--areas ` +: Optional: Areas affected (comma-separated or specify multiple times). + +`--config ` +: Optional: Path to the changelog.yml configuration file. Defaults to `docs/changelog.yml`. + +`--description ` +: Optional: Additional information about the change (max 600 characters). + +`--feature-id ` +: Optional: Feature flag ID + +`--highlight ` +: Optional: Include in release highlights. + +`--impact ` +: Optional: How the user's environment is affected. + +`--issues ` +: Optional: Issue numbers (comma-separated or specify multiple times). + +`--output ` +: Optional: Output directory for the changelog fragment. Defaults to current directory. + +`--products >` +: Required: Products affected in format "product target lifecycle, ..." (for example, `"elasticsearch 9.2.0 ga, cloud-serverless 2025-08-05"`). +: The valid product identifiers are listed in [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml). +: The valid lifecycles are listed in [ChangelogConfiguration.cs](https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs). + +`--pr ` +: Optional: Pull request number. + +`--subtype ` +: Optional: Subtype for breaking changes (for example, `api`, `behavioral`, or `configuration`). +: The valid subtypes are listed in [ChangelogConfiguration.cs](https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs). + +`--title ` +: Required: A short, user-facing title (max 80 characters) + +`--type ` +: Required: Type of change (for example, `feature`, `enhancement`, `bug-fix`, or `breaking-change`). +: The valid types are listed in [ChangelogConfiguration.cs](https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs). diff --git a/docs/cli/release/index.md b/docs/cli/release/index.md new file mode 100644 index 000000000..37c29bb46 --- /dev/null +++ b/docs/cli/release/index.md @@ -0,0 +1,11 @@ +--- +navigation_title: "release" +--- + +# Release doc commands + +These commands are associated with product release documentation. + +## Changelog commands + +- [changelog add](changelog-add.md) - Create a changelog file diff --git a/docs/contribute/_snippets/changelog-fields.md b/docs/contribute/_snippets/changelog-fields.md new file mode 100644 index 000000000..d9a8d76a4 --- /dev/null +++ b/docs/contribute/_snippets/changelog-fields.md @@ -0,0 +1,83 @@ + +```yaml +##### Required fields ##### +title: + +# A required string that is a short, user-facing headline +# Max 80 characters + +type: + +# A required string that contains the type of change. +# Refer to https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs for the acceptable values. + +products: + +# A required array of objects that denote the affected products and their target release. + + - product: + + # A required string with a predefined product ID used for release note routing, + # filters, and categorization. + # Refer to https://github.com/elastic/docs-builder/blob/main/config/products.yml for the acceptable values. + + target: + + # An optional string that facilitates pre-release doc previews. + # For products with version releases, it contains the target version number (V.R.M). + # For products with date releases, it contains the target release date + # or the date the PR was merged. + + lifecycle: + + # An optional string for new features and enhancements that have a specific availability. + # Refer to https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs for the acceptable values. + +##### Optional fields ##### +action: + +# An optional string that describes what users must do to mitigate the impact +# of a breaking change or known issue. + +areas: + +# An optional array of strings that denotes the parts/components/services of the +# product that are specifically affected. +# The list of valid values will vary by product. +# The docs for each release typically group the changes by type then by area. + +description: + +# An optional string that provides additional information about what has changed. +# Max 600 characters + +feature-id: + +# An optional string to associate a feature or enhancement with a unique feature flag + +highlight: + +# An optional boolean for items that should be included in release highlights +# or the UI to draw users' attention. + +impact: + +# An optional string that describes how the user's environment is/will be +# affected by a breaking change. + +issues: + +# An optional array of strings that contain URLs for issues that are relevant to the PR. +# They are externalized in the release docs so users can follow the links and +# understand the context. + +pr: + +# An optional string that contains the pull request identifier. +# It is externalized in the release docs so users can follow the link and find more details. + +subtype: + +# An optional string that applies only to breaking changes and further subdivides that type. +# Refer to https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs for the acceptable values. +``` diff --git a/docs/contribute/changelog.md b/docs/contribute/changelog.md new file mode 100644 index 000000000..3cff558cd --- /dev/null +++ b/docs/contribute/changelog.md @@ -0,0 +1,109 @@ +# Add changelog entries + +The `docs-builder changelog add` command creates a new changelog file from command-line input. +By adding a file for each notable change, you can ultimately generate release documention with a consistent layout for all your products. + +:::{note} +This command is associated with an ongoing release docs initiative. +Additional workflows are still to come for managing the list of changelogs in each release. +::: + +The command generates a YAML file that uses the following schema: + +:::{dropdown} Changelog schema +::::{include} /contribute/_snippets/changelog-fields.md +:::: +::: + +## Command options + +The command supports all of the following options, which generally align with fields in the changelog schema: + +```sh +Usage: changelog add [options...] [-h|--help] [--version] + +Add a new changelog fragment from command-line input + +Options: + --title Required: A short, user-facing title (max 80 characters) (Required) + --type Required: Type of change (feature, enhancement, bug-fix, breaking-change, etc.) (Required) + --products > Required: Products affected in format "product target lifecycle, ..." (e.g., "elasticsearch 9.2.0 ga, cloud-serverless 2025-08-05") (Required) + --subtype Optional: Subtype for breaking changes (api, behavioral, configuration, etc.) (Default: null) + --areas Optional: Area(s) affected (comma-separated or specify multiple times) (Default: null) + --pr Optional: Pull request URL (Default: null) + --issues Optional: Issue URL(s) (comma-separated or specify multiple times) (Default: null) + --description Optional: Additional information about the change (max 600 characters) (Default: null) + --impact Optional: How the user's environment is affected (Default: null) + --action Optional: What users must do to mitigate (Default: null) + --feature-id Optional: Feature flag ID (Default: null) + --highlight Optional: Include in release highlights (Default: null) + --output Optional: Output directory for the changelog fragment. Defaults to current directory (Default: null) + --config Optional: Path to the changelog.yml configuration file. Defaults to 'docs/changelog.yml' (Default: null) +``` + +### Product format + +The `--products` parameter accepts products in the format `"product target lifecycle, ..."` where: + +- `product` is the product ID from [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml) (required) +- `target` is the target version or date (optional) +- `lifecycle` is one of: `preview`, `beta`, or `ga` (optional) + +Examples: + +- `"kibana 9.2.0 ga"` +- `"cloud-serverless 2025-08-05"` +- `"cloud-enterprise 4.0.3, cloud-hosted 2025-10-31"` + +## Changelog configuration + +Some of the fields in the changelog accept only a specific set of values. + +:::{important} + +- Product values must exist in [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml). Invalid products will cause the command to fail. +- Type, subtype, and lifecycle values must match the available values defined in [ChangelogConfiguration.cs](https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs). Invalid values will cause the command to fail. +::: + +If you want to further limit the list of values, you can optionally create a configuration file. +Refer to [changelog.yml.example](https://github.com/elastic/docs-builder/blob/main/config/changelog.yml.example). + +By default, the command checks the following path: `docs/changelog.yml`. +You can specify a different path with the `--config` command option. + +If a configuration file exists, the command validates all its values before generating the changelog file: + +- If the configuration file contains `lifecycle`, `product`, `subtype`, or `type` values that don't match the values in `products.yml` and `ChangelogConfiguration.cs`, validation fails. The changelog file is not created. +- If the configuration file contains `areas` values and they don't match what you specify in the `--areas` command option, validation fails. The changelog file is not created. + +## Examples + +The following command creates a changelog for a bug fix that applies to two products: + +```sh +docs-builder changelog add \ + --title "Fixes enrich and lookup join resolution based on minimum transport version" \ + --type bug-fix \ <1> + --products "elasticsearch 9.2.3, cloud-serverless 2025-12-02" \ <2> + --areas "ES|QL" + --pr "https://github.com/elastic/elasticsearch/pull/137431" <3> +``` + +1. The type values are defined in [ChangelogConfiguration.cs](https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs). +2. The product values are defined in [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml). +3. At this time, the PR value can be a number or a URL; it is not validated. + +The output file has the following format: + +```yaml +pr: https://github.com/elastic/elasticsearch/pull/137431 +type: bug-fix +products: +- product: elasticsearch + target: 9.2.3 +- product: cloud-serverless + target: 2025-12-02 +title: Fixes enrich and lookup join resolution based on minimum transport version +areas: +- ES|QL +``` diff --git a/docs/contribute/index.md b/docs/contribute/index.md index 0386949cd..21240317b 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -10,6 +10,7 @@ Use these guides for tasks like managing documentation files and folders, config - [Move files and folders](move.md): Move files or folders and automatically update all links in the documentation. - [Manage redirects across doc sets](redirects.md): Set up redirects when moving or deleting pages to prevent broken links. +- [Add changelog entries](changelog.md): Create changelog fragments using the command-line interface. ## Repository management