Release Notes Overhaul

[IanMadd]

General details

People are looking for three features:

• Searchable release notes. This would have to be deployed as static files using Hugo and not JavaScript so that page or pages could be indexed with Swiftype.
• Single page release notes. A single page of release notes so that the user could scroll through the entire page without having to click on each individual page if they're looking for a specific feature. This could be done in JavaScript. Ideally we could find a way to do this with Hugo.
• Product release dates. Add product release dates to the release note pages like in the Automate release notes.
• Replace Showdown JS Markdown converter. Showdown hasn't been updated in a few years and now we're getting security vulnerability warnings from dependabot.

Review

Name of technical reviewer: Me

Searchable Release Notes

Original Issue: #3519

The big issue here is that there is currently no way to get Hugo to pull in MD files from packages.chef.io and deploy them as a static page and Swiftype can't index text that's not static.

Options:

• Hugo could grab Markdown text from a JSON file from packages.chef.io and deploy it. We'd have to convert each MD file to JSON and anything that uses those files (downloads.chef.io) would have to be converted to handle JSON too.
• Hugo could pull that content from another GitHub repository using the GitHub API and Hugo's getJSON.
• Hugo could pull that content if we deployed the release note MD files from docs.chef.io from the static directory. Release notes could be released from docs.chef.io/data/release_notes/PRODUCT/VERSION.md. This would be the fastest option as far as Hugo build times are concerned.
• Use curl to copy files before a build into static/data/release_notes/*. It would have to get the version numbers for each product, then loop through and grab each file. This could also be set to run only for a production deploy.
• Someone is making a getResource function in Hugo which could grab MD files. Wait for them to finish which could be many months or years.

The downside of using Hugo's getJSON function is that it will add a considerable amount of time to the build process. I could set it so that Hugo only builds the release notes on a production deploy.

Single Page Release Notes

Original Issue: #3273

This could be done in JavaScript. We could have one page for all release notes for a product and then another page with the existing style that lists a single page of release notes.

Product release dates

Original Issue: #3510

As far as I know there's no list or file of release note dates for products. It seems like there should be one somewhere though. The Automate release notes gets the release date by parsing the name of each MD file.

[kagarmoe]

Look into Habitat Release Notes #3047

[IanMadd]

TODO:

• Manage release notes Automate Manage release notes #3621
• Backend release notes Add chef backend to the docs site release notes #3614
• [ ] Dates for each release Promote date should be in the release note pages #3510
• release notes for inspec cloud resources
  • move release notes JSON to assets dir in inspec cloud resources and update release notes expeditor scripts
• CSS

[IanMadd]

Closed with #3623