Using Expeditor to manage your Changelog

Chef Expeditor incorporates custom Changelog management functionality that was inspired by the Github Changelog Generator but with a few specific differences:

  1. It does not query the Github API to generate the changelog file.
  2. It does not overwrite the existing changelog file.

This functionality exists to offer a consistent method of keeping changelog across all Chef Software’s projects. To see examples of different types of changelogs managed by Expeditor, check out the following repositories:

Getting Started

To get started managing your changelog, you’ll need to do the following:

  1. Add the necessary settings, subscriptions, and actions to your .expeditor/config.yml.
  2. Add the necessary blocks to your changelog file.
.expeditor/config.yml
---
github:
  changelog_file: CHANGELOG.md

changelog:
  rollup_header: Changes not yet released to stable

subscriptions:
  - workload: pull_request_merged:{{agent_id}}:*
    actions:
      - built_in:update_changelog
  - workloads: project_promoted:{{agent_id}}:*
    actions:
      - built_in:rollover_changelog
CHANGELOG.md
... optional header material

<!-- latest_release -->
<!-- latest_release -->

<!-- release_rollup -->
<!-- release_rollup -->

<!-- latest_stable_release -->
<!-- latest_stable_release -->

... any existing content you might have

Usage

The Expeditor changelog functionality works by leveraging three comment blocks inside your changelog.

  1. latest_release
  2. release_rollup
  3. latest_stable_release

When you merge a pull request, Expeditor injects a line item representing the changes into your changelog. This is handled by the built_in:update_changelog action (commonly) in response to the pull_request_merged workload. The built_in:update_changelog action will add the new line item to both the latest_release and release_rollup blocks.

By default, Expeditor adds line items to the “Merged Pull Requests” category. You can specify as many categories as you’d like, and associated them with GitHub labels using the changelog.categories configuration setting.

If you look at an example patchdiff, it might look like this:

- <!-- latest_release 0.9.8-->
- ## [v0.9.8](https://github.com/chef/example/tree/v0.9.8) (2019-01-01)
+ <!-- latest_release 0.9.9 -->
+ ## [v1.0.0](https://github.com/chef/project/tree/v0.9.9) (2019-01-02)

  #### Merged Pull Requests
- - pull request that created version 0.9.8
+ - pull request that created version 0.9.9
  <!-- latest_release -->

  <!-- release_rollup since=0.9.5 -->
  ### Changes not yet released to stable

  #### Merged Pull Requests
+ - pull request that created version 0.9.9 <!-- 0.9.9 -->
  - pull request that created version 0.9.8 <!-- 0.9.8 -->
  - pull request that created version 0.9.7 <!-- 0.9.7 -->
  - pull request that created version 0.9.6 <!-- 0.9.6 -->
  - pull request that created version 0.9.5 <!-- 0.9.5 -->
  - pull request that created version 0.9.4 <!-- 0.9.4 -->
  <!-- release_rollup -->

  <!-- latest_stable_release -->
  <!-- latest_stable_release -->

You’ll notice that there is a comment at the end of the line item with the version number. Expeditor uses this during the built_in:rollover_changelog action to determine which line items should be moved to latest_stable_release when the project is promoted.

Line items are added to your changelog every time you merge a pull request. Expeditor uses latest_release block to contain the most recent change while release_rollup contains all the line items since the last time you promoted the project.

When we promote our sample project, Expeditor executes the built_in:rollover_changelog action (as defined by the subscription to the project_promoted workload). When that happens, we will:

  1. Move the contents of the latest_stable_release block out of the current block
  2. Move the impacted line items from the release_rollup to the latest_stable_release blocks

It’s important to note that we do not always promote the latest version of a project (hence why we keep the version associated with the line items). In this example, let’s say that we promote version 0.9.7 to stable. Expeditor moves the line items for versions 0.9.7 and below into the latest_stable_release block while line items for newer versions should stay in the release rollup.

  <!-- latest_release 0.9.9 -->
  ## [v1.0.0](https://github.com/chef/project/tree/v0.9.9) (2019-01-02)

  #### Merged Pull Requests
  - pull request that created version 0.9.9
  <!-- latest_release -->

  <!-- release_rollup since=0.9.5 -->
  ### Changes not yet released to stable

  #### Merged Pull Requests
  - pull request that created version 0.9.9 <!-- 0.9.9 -->
  - pull request that created version 0.9.8 <!-- 0.9.8 -->
- - pull request that created version 0.9.7 <!-- 0.9.7 -->
- - pull request that created version 0.9.6 <!-- 0.9.6 -->
- - pull request that created version 0.9.5 <!-- 0.9.5 -->
- - pull request that created version 0.9.4 <!-- 0.9.4 -->
  <!-- release_rollup -->

  <!-- latest_stable_release -->
+ ## [v0.9.7](https://github.com/chef/project/tree/v0.9.7) (2019-01-02)
+
+ #### Merged Pull Requests
+ - pull request that created versino 0.9.7
+ - pull request that created versino 0.9.6
+ - pull request that created versino 0.9.5
+ - pull request that created versino 0.9.4
  <!-- latest_stable_release -->