Configure changelogs

Before you can use the docs-builder changelog commands, you must evaluate your GitHub label strategy and verify that the necessary product metadata exists. You can then set up a changelog configuration file to make the content workflow more automated and repeatable.

1. Ensure that your products exist in products.yml. Products that only need release notes (not public documentation) can be added with features: { public-reference: false }. For more information, refer to Products.

2. Optional: Choose the GitHub labels that you'll use to automatically derive some changelog fields.

   1. Create labels for types. The supported types are defined in ChangelogEntryType.cs. At a minimum, add labels for the feature, bug-fix, and breaking-change types.

   2. Create labels for products. If your repo only pertains to a single product or you don't want to use labels to accomplish this classification, this step is not required.

   3. Create labels for areas (or "features" or "components") of your products. If you don't want to show categories (other than the default "type" categories) in your documentation, this step is not required.

   4. Create labels to opt in or out of changelogs. For example, create non-issue or release_notes:skip labels for PRs that shouldn't have changelogs. Alternatively, create a @Public label to identify PRs that should have changelogs. You can only choose one label strategy for this behavior: exclusion or inclusion.

   5. Create labels for highlights. This step is not required unless you want to publish release highlights.

3. If you'll be accessing GitHub from the command line, set up the necessary privileges as described in the following section.

Any of the docs-builder changelog commands that access GitHub require authority to view your pull requests and issues. For example, this authority is required if you'll be running any of these changelog commands from the command line: changelog add, changelog bundle, changelog gh-release.

You must log into GitHub or set the GITHUB_TOKEN (or GH_TOKEN ) environment variable with a sufficient personal access token (PAT) to pull information from your repository. Otherwise, there will be fetch failures when you access private repositories and you might also encounter GitHub rate limiting errors.

For example, to create a new token with the minimum authority to read pull request details:

1. Go to GitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens.
2. Click Generate new token.
3. Give your token a descriptive name (such as "docs-builder changelog").
4. Under Resource owner if you're an Elastic employee, select Elastic.
5. Set an expiration date.
6. Under Repository access, select Only select repositories and choose the repositories you want to access.
7. Under Permissions > Repository permissions, set Pull requests to Read-only. If you want to be able to read issue details, do the same for Issues.
8. Click Generate token.
9. Copy the token to a safe location and use it in the GITHUB_TOKEN environment variable.

The changelog configuration file:

• Defines acceptable product, type, subtype, and lifecycle values.
• Sets default options, such as whether to extract issues and release note text from pull requests.
• Defines profiles for simplified bundle creation.
• Prevents the creation of changelogs when certain labels are present.
• Excludes changelogs from bundles based on their areas, types, or products.

You can use the changelog init command to create the changelog configuration file and folder structure automatically.

For example, run the following command in your GitHub repo's root directory:

docs-builder changelog init
		

1. Find the configuration file. By default, the changelog init command creates docs/changelog.yml. If you move or rename this file, there will be extra steps when you configure its usage.
2. Review the settings and update them based on your preferences. For descriptions of all the settings, refer to Changelog configuration reference. For example:
   • To limit the acceptable values, update lifecycles and products.
   • To set the changelog file name pattern, update filename.
   • To control what is extracted from GitHub, update extract.
   • To change bundle default behaviour or create reusable profiles, update bundle.
   • If you have GitHub labels to set changelog areas, types, or products, update pivot.
   • If you have GitHub labels to opt in or out of changelogs, update rules.create.
   • If you want to filter changelogs in or out of release bundles based on their area, type, or products, update rules.bundle.

For example, a simple docs/changelog.yml looks like this:

filename: timestamp
products:
  available: []
extract:
  release_notes: true
  issues: true
  strip_title_prefix: false
lifecycles:
  - preview
  - beta
  - ga
pivot:
  types:
    breaking-change:
      labels: ">breaking, >bc"
    bug-fix: ">bug"
    feature:
		

For the most up-to-date changelog configuration options, refer to changelog.example.yml.

After you've created a config file, all subsequent changelog commands can use it. By default, they look for changelog.yml by checking ./changelog.yml then ./docs/changelog.yml relative to your current directory. Most changelog commands allow you to specify a different path with the --config option.

1. Start creating changelog files.
2. You might need to make further changes to your configuration file after you've performed a few tests. Likewise you might need to add bundle settings or profiles when you're ready to create release bundles.