RFC: add feature tags to changelog

[daledupreez]

Changes proposed in this Pull Request:

We have been discussing how to improve our changelog for our next release. I had a discussion with @diegocurbelo yesterday that solidified this idea for me: what if our automated changelog script could tag and group entries so it's easier to identify what changes did/do? That should hugely simplify the process of collating and organising our release notes and changelogs in future.

The implementation is pretty straightforward:

• When starting a new project/feature, add an entry to .changelog.features.json
• When making changes related to a feature, allow developers to pick from the available features (or skip that entirely)
• If a change was for a feature, add a [tag] to the changelog entry for that specific feature

Then, when we're collating release notes or prepping the changelog for release, we can easily group features and remove any noisy/unnecessary items.

Open questions

• How should we manage our changelog over time? Should we keep or remove the tags when we release? How should we manage .changelog.features.json over time? Should we keep all features in there indefinitely? Or clean it up from time to time?
  • The combined answers have implications for the usability of our basic changelog:
    • If we clean up the changelog for each release and remove all the tags, we can keep the JSON list of features small. It would mean that our develop branch would need to pick up release notes from the release, and we'd rewrite the changelog for each release, with some extra work for late patches/fixes flowing in
    • If we keep the tags in the changelog, that will generate a lot of noise. And we then need to consider whether we use a different format for the feature list, as we'll either need to maintain it in perpetuity so folks can identify what each tag means, or we'll need to keep it clean but then leave the changelog with indecipherable tags.
• Are there some internal features/categories that might make sense? e.g. CI/Tests, Tools?
  • Not directly related, but maybe we should have a separate Test option for the basic changelog types?

@woocommerce/quark, please share feedback on the approach as much as the code!

Testing instructions

• Check out this branch locally
• Run npm run changelog
• Pick a change type
• Enter a changelog message
• Confirm that you see a Is this change for a feature? prompt
• Enter n or N to indicate it is not related to a feature
• Verify that you get a changelog entry without a tag at the end of the current version's entries
• Run npm run changelog
• Pick a change type
• Enter a changelog message
• Confirm that you see a Is this change for a feature? prompt
• Enter y or Y to indicate the change is related to a feature
• Confirm that you see the following list of options:

  Never mind (No feature) 
  [ACSS] - Add support for ACSS payments in Canada (Local payment method) 
  [Amazon Pay] - Add support for Amazon Pay to express checkout (Express checkout) 
  [BECS] - Add support for BECS Direct Debits in Australia (Local payment method) 
  [BLIK] - Add support for BLIK payments in Poland (Local payment method) 
  [Settings Sync] - Synchronize payment method settings with Stripe dashboard 
  [Smart Checkout] - Add support for Smart Checkout/ Dynamic Payment Element 

• Pick "Never mind (No feature)"
• Verify that the generated entry doesn't have a tag, and appears at the end of the file
• Walk through the steps again and pick one of the features this time
• Verify that the generated entry includes the [Tag] from the selected list and appears at the end of the list, e.g.

* [Amazon Pay] Fix - Your changelog message

• Repeat the steps above with a different tag, and confirm it appears below the entry above
• Repeat the steps above with the same tag as the first tag, and confirm it appears immediately after the first entry for that tag

To clean up after you're done, run git restore changelog.txt readme.txt

Screenshot

---

• Covered with tests (or have a good reason not to test in description ☝️)
• [N/A] Tested on mobile (or does not apply)

Changelog entry

• This Pull Request does not require a changelog entry. (Comment required below)

Changelog Entry Comment

Comment

Post merge

• [N/A] Added testing instructions to the Release Testing Instructions wiki page (or does not apply)
• [N/A] Added the needs docs label (or does not apply)
• [N/A] Included this PR in the Release Thread scope (or does not apply)

[malithsen]

How should we manage our changelog over time?

What do we think about pulling the feature list from the Linear API? We could fetch a list of active projects (or labels) in the Quark team to populate changelog.features.json to reduce some of the burden associated with maintaining a manual list. I experimented with Linear's GraphQL API, and the list can be obtained fairly easily with a query like below.

query {
    projects(filter: { status: { type: { eq: "started" } } }) {
        nodes {
            name
        }
    }
}

One issue is that we need an API token, so an open-source contributor will not be able to use this script if we rely solely on the Linear API.