Skip to content

Commit be4574d

Browse files
lcawllcawl
committed
More edits
1 parent febc68d commit be4574d

File tree

2 files changed

+182
-32
lines changed

2 files changed

+182
-32
lines changed

‎docs/contribute/_snippets/changelog-fields.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
2+
```yaml
3+
##### Required fields #####
4+
title:
5+
6+
# A required string that is a short, user-facing headline
7+
# Max 80 characters
8+
9+
type:
10+
11+
# A required string that contains the type of change.
12+
# It can be one of:
13+
# - feature: new functionality
14+
# - enhancement: extends functionality but does not break or fix existing behavior
15+
# - bug-fix: fixes a problem in a previous version
16+
# - known-issue: problems that we are aware of in a given version
17+
# - breaking-change: a change to previously-documented behavior
18+
# - deprecation: functionality that is being removed in a later release
19+
# - docs: major documentation updates or reorgs
20+
# - regression: functionality that no longer works or behaves incorrectly
21+
# - security: an advisory about potential security vulnerabilities
22+
# - other: does not fit into any of the other categories
23+
24+
products:
25+
26+
# A required array of objects that denote the affected products and their target release.
27+
28+
- product:
29+
30+
# A required string with a predefined product ID used for release note routing,
31+
# filters, and categorization.
32+
33+
target:
34+
35+
# An optional string that facilitates pre-release doc previews.
36+
# For products with version releases, it contains the target version number (V.R.M).
37+
# For products with date releases, it contains the target release date
38+
# or the date the PR was merged.
39+
40+
lifecycle:
41+
42+
# An optional string for new features and enhancements that have a specific availability.
43+
# It can be one of the following:
44+
# - preview
45+
# - beta
46+
# - ga
47+
48+
##### Optional fields #####
49+
action:
50+
51+
# An optional string that describes what users must do to mitigate the impact
52+
# of a breaking change or known issue.
53+
54+
areas:
55+
56+
# An optional array of strings that denotes the parts/components/services of the
57+
# product that are specifically affected.
58+
# The list of valid values will vary by product.
59+
# The docs for each release typically group the changes by type then by area.
60+
61+
description:
62+
63+
# An optional string that provides additional information about what has changed.
64+
# Max 600 characters
65+
66+
feature-id:
67+
68+
# An optional string to associate a feature or enhancement with a unique feature flag
69+
70+
highlight:
71+
72+
# An optional boolean for items that should be included in release highlights
73+
# or the UI to draw users' attention.
74+
75+
impact:
76+
77+
# An optional string that describes how the user's environment is/will be
78+
# affected by a breaking change.
79+
80+
issues:
81+
82+
# An optional array of strings that contain URLs for issues that are relevant to the PR.
83+
# They are externalized in the release docs so users can follow the links and
84+
# understand the context.
85+
86+
pr:
87+
88+
# An optional string that contains the pull request identifier.
89+
# It is externalized in the release docs so users can follow the link and find more details.
90+
91+
subtype:
92+
93+
# An optional string that applies only to breaking changes and further subdivides that type.
94+
# It can be one of:
95+
# - api: refers to changes that break an api
96+
# - behavioral: refers to changes the way something works
97+
# - configuration: refers to changes that break the configuration
98+
# - dependency: refers to changes like removing support for third-party products
99+
# - subscription: refers to changes that break licensing behavior
100+
# - plugin: refers to changes that break a plugin
101+
# - security: refers to changes that break authentication, authorization, or permissions
102+
# - other: does not fit into any of the other categories
103+
```

‎docs/contribute/changelog.md‎

Lines changed: 79 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,23 @@
11
# Add changelog entries
22

3-
The `docs-builder changelog add` command creates a new changelog fragment file from command-line input. This is useful for creating changelog entries as part of your development workflow.
3+
The `docs-builder changelog add` command creates a new changelog file from command-line input.
4+
By adding a file for each notable change, you can ultimately generate release documention with a consistent layout for all your products.
45

5-
## `docs-builder changelog add`
6-
7-
Create a new changelog fragment with required and optional fields. For example:
8-
9-
```sh
10-
docs-builder changelog add \
11-
--title "Fixes enrich and lookup join resolution based on minimum transport version" \
12-
--type bug-fix \
13-
--products "elasticsearch 9.2.3, cloud-serverless 2025-12-02" \
14-
--areas "ES|QL"
15-
--pr "https://github.com/elastic/elasticsearch/pull/137431"
16-
```
17-
18-
:::{important}
19-
20-
- 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.
21-
- 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.
22-
- The command validates all values before generating the changelog file. If validation fails, no file is created.
23-
- At this time, the PR value can be a number or a URL; it is not validated.
6+
:::{note}
7+
This command is associated with an ongoing release docs initiative.
8+
Additional workflows are still to come for managing the list of changelogs in each release.
249
:::
2510

26-
## Product format
27-
28-
The `--products` parameter accepts products in the format `"product target lifecycle, ..."` where:
29-
30-
- `product` is the product ID from [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml) (required)
31-
- `target` is the target version or date (optional)
32-
- `lifecycle` is one of: `preview`, `beta`, or `ga` (optional)
11+
The command generates a YAML file that uses the following schema:
3312

34-
Examples:
13+
:::{dropdown} Changelog schema
14+
::::{include} /contribute/_snippets/changelog-fields.md
15+
::::
16+
:::
3517

36-
- `"kibana 9.2.0 ga"`
37-
- `"cloud-serverless 2025-08-05"`
38-
- `"cloud-enterprise 4.0.3, cloud-hosted 2025-10-31"`
18+
## Command options
3919

40-
## {{dbuild}} changelog add --help
20+
The command supports all of the following options, which generally align with fields in the changelog schema:
4121

4222
```sh
4323
Usage: changelog add [options...] [-h|--help] [--version]
@@ -60,3 +40,70 @@ Options:
6040
--output <string?> Optional: Output directory for the changelog fragment. Defaults to current directory (Default: null)
6141
--config <string?> Optional: Path to the changelog.yml configuration file. Defaults to 'docs/changelog.yml' (Default: null)
6242
```
43+
44+
### Product format
45+
46+
The `--products` parameter accepts products in the format `"product target lifecycle, ..."` where:
47+
48+
- `product` is the product ID from [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml) (required)
49+
- `target` is the target version or date (optional)
50+
- `lifecycle` is one of: `preview`, `beta`, or `ga` (optional)
51+
52+
Examples:
53+
54+
- `"kibana 9.2.0 ga"`
55+
- `"cloud-serverless 2025-08-05"`
56+
- `"cloud-enterprise 4.0.3, cloud-hosted 2025-10-31"`
57+
58+
## Changelog configuration
59+
60+
Some of the fields in the changelog accept only a specific set of values.
61+
62+
:::{important}
63+
64+
- 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.
65+
- 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.
66+
:::
67+
68+
If you want to further limit the list of values, you can optionally create a configuration file.
69+
Refer to [changelog.yml.example](https://github.com/elastic/docs-builder/blob/main/config/changelog.yml.example).
70+
71+
By default, the command checks the following path: `docs/changelog.yml`.
72+
You can specify a different path with the `--config` command option.
73+
74+
If a configuration file exists, the command validates all its values before generating the changelog file:
75+
76+
- 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.
77+
- 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.
78+
79+
## Examples
80+
81+
The following command creates a changelog for a bug fix that applies to two products:
82+
83+
```sh
84+
docs-builder changelog add \
85+
--title "Fixes enrich and lookup join resolution based on minimum transport version" \
86+
--type bug-fix \ <1>
87+
--products "elasticsearch 9.2.3, cloud-serverless 2025-12-02" \ <2>
88+
--areas "ES|QL"
89+
--pr "https://github.com/elastic/elasticsearch/pull/137431" <3>
90+
```
91+
92+
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).
93+
2. The product values are defined in [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml).
94+
3. At this time, the PR value can be a number or a URL; it is not validated.
95+
96+
The output file has the following format:
97+
98+
```yaml
99+
pr: https://github.com/elastic/elasticsearch/pull/137431
100+
type: bug-fix
101+
products:
102+
- product: elasticsearch
103+
target: 9.2.3
104+
- product: cloud-serverless
105+
target: 2025-12-02
106+
title: Fixes enrich and lookup join resolution based on minimum transport version
107+
areas:
108+
- ES|QL
109+
```

0 commit comments

Comments
 (0)