docs: Initial release notes/migration guide support

[petejohanson]

Add the initial infrastructure for formal release notes and migrations guides, with a retroactive v0.3 set of docs as a start.

PR check-list

• Branch has a clean commit history
• Additional tests are included, if changing behaviors/core code that is testable.
• Proper Copyright + License headers added to applicable files (Generally, we stick to "The ZMK Contributors" for copyrights to help avoid churn when files get edited)
• Pre-commit used to check formatting of files, commit messages, etc.
• Includes any necessary documentation changes.

[caksoylar]

Not sure it is worth it at this point, but the wired split PR's refactor moved a few headers around and renamed some functions: 4a2189d

[petejohanson]

Fair. Added a bullet item.

[caksoylar]

Can we either add a description metadata here or a introductory sentence? Otherwise the doccard in category index page shows "Change summary":

[petejohanson]

Added a description to the front matter.

[joelspadin]

ZMK CLI has a zmk version <tag> command that will update both the manifest and actions workflow files. It looks like I forgot to document that on /docs/zmk-cli when I added it though. I think it would be good to document that as one way you can pin a specific version, alongside the steps for doing it manually.

[petejohanson]

Just pushed a small addition in the v0.3 migration guide, if you could please verify it matches the expectation.

[joelspadin]

!(thing ?? false) is equivalent to !thing, since !null == !undefined == true

If the intent is to fall back to false if args.docs doesn't include an item, then you need a ?. at the first thing that could be undefined

args.docs.find(...)?.frontMatter.unlisted ?? false

though the fact that this isn't a problem right now tells me that args.docs is probably guaranteed to contain every item?

[petejohanson]

We specifically need to handle the scenario we don't have a value for unlisted in the frontMatter. In that scenario, unlisted should be false. So we need to default to false only if the value isn't explicitly set/present in the frontMatter. Then we need to invert the value, for the expected filtering.

[joelspadin]

If frontMatter doesn't have a value for unlisted, then frontMatter.unlisted is undefined. The only cases where ?? evaluates the right-hand side are when the left-hand side is null or undefined, and !null and !undefined are both true, so !(frontMatter.unlisted ?? false) is equivalent to !frontMatter.unlisted.

[petejohanson]

Indeed. My tired brain somehow screwed up my testing of that last night. Changed.

[joelspadin]

Consider pulling part of this out into a helper function with a name that makes it clearer what the code is intended to do. Some ideas for that:

// Top-level helper function
function getFrontMatter(docs, item) {
  return docs.find((d) => d.id === item.id);
}
...
const sidebarItems = ...
const filtered = sidebarItems.filter((item) => !getFrontMatter(args.docs, item).unlisted);

// Lambda that captures args.docs so it doesn't need to be passed in as an argument
const getFrontMatter = (item) => args.docs.find((d) => d.id === item.id;

const sidebarItems = ...
const filtered = sidebarItems.filter((item) => !getFrontMatter(item).unlisted);

// Pull the whole thing into a lambda
const isListed = (item) => !args.docs.find((d) => d.id === item.id).frontMatter.unlisted;

const sidebarItems = (await defaultSidebarItemsGenerator(args)).filter(isListed);

[petejohanson]

Tweaked a bit.

[joelspadin]

It feels like there's a lot of overlap between the release notes and migration guides pages for the same release. Both list breaking changes. One of them lists changes needed to user configs, while the other lists changes that might be needed to modules, which feels like something that belongs more in a migration guide?

IMO, we should either combine these into single pages for each release, or we should at the very least remove any duplicate info and make sure that every release notes page links to the matching migration guide page.

[petejohanson]

So.... Yeah, I've been struggling with this. In particular, this v0.3 doesn't have a particularly significant set of release notes, so it feels a bit silly to have two docs. For larger releases, I think having this split will help bring clarity for folks who just need to go through the upgrade steps. I will move the module change not to the upgrade notes for more consistency, as a bare minimum here.