Release Best Practices Guide

[riverma]

Purpose

• A guide to help make release-making as consistent and automated as possible
• PLEASE REVIEW LIVE VERSION HERE: https://github.com/NASA-AMMOS/slim/tree/issue-97/docs/guides/documentation/releases
  • Help provide feedback in this PR by testing it out on your project!

    Proposed Changes

• [ADD] A draft guide text
• [ADD] A template release.yml file to help make release notes look good and standardized with categories
• [ADD] A python script to help aggregate release notes from multiple GitHub repositories into a single file

  Issues

• 97

  Testing

• Guide successfully rendered in SLIM docusaurus view (locally)
• See template release.yml in action for the SLIM project here: https://github.com/riverma/slim/releases/tag/v1.4.0

• Automation release notes aggregation script tested successfully on all SLIM repositories with the following output:

  $ python gh_aggregate_release_notes.py gh_aggregate_release_notes_config.yml 
  Downloading release notes: 100%|█████████████████████████████████████████████████████████████| 2/2 [00:00<00:00,  3.47it/s]
  # slim-starterkit-python
  
  ## What's Changed
  * Release Update of Python Starter Kit with Scanning by @ingyhere in https://github.com/NASA-AMMOS/slim-starterkit-python/pull/14
  * NASA-AMMOS/slim#89: Functional GitHub Actions-based secrets detection… by @ingyhere in https://github.com/NASA-AMMOS/slim-starterkit-python/pull/10
  * NASA-AMMOS/slim#25: Functional GitHub Actions-based SCRUB (CodeQL) analysis... by @ingyhere in https://github.com/NASA-AMMOS/slim-starterkit-python/pull/11
  * NASA-AMMOS/slim#110: Functional Pylint static code analysis. ... by @ingyhere in https://github.com/NASA-AMMOS/slim-starterkit-python/pull/12
  * Add Governance documentation by @jpl-jengelke in https://github.com/NASA-AMMOS/slim-starterkit-python/pull/9
  
  **Full Changelog**: https://github.com/NASA-AMMOS/slim-starterkit-python/compare/1.0.0...1.0.1
  
  # slim-starterkit
  
  ## What's Changed
  * Remove duplicate text. Standardize text for link insertion. by @jpl-jengelke in https://github.com/NASA-AMMOS/slim-starterkit/pull/2
  
  ## New Contributors
  * @jpl-jengelke made their first contribution in https://github.com/NASA-AMMOS/slim-starterkit/pull/2
  
  **Full Changelog**: https://github.com/NASA-AMMOS/slim-starterkit/commits/v1.0.0
  

[riverma]

@mike-gangl - would this help Unity make releases across many repositories? Let me know what you think.

[riverma]

Received a use case from the OPERA project regarding the following question: how do we safeguard that a super release will include the right versioned repositories?

In other words, can this best practice guide PR help ensure that a particular build or release of many repositories doesn't lead to a situation where the wrong version of a particular repository's code is mixed up with another repository during a super release?

CC @philipjyoon @hhlee445

[mike-gangl]

@mike-gangl - would this help Unity make releases across many repositories? Let me know what you think.

So in terms of unity, we keep a changelog which is where most release notes comes from; thought this can still be very useful- there is a bit of a difference in what goes into a changelog and what we would describe at a system level release (which, in my opinion, is slightly different than these super releases. I can see "super releases" on a service area basis. The System releases, however, would be manually currated and de-jargoned for a slightly different audience.