OSCAL Patch (Hot Fix) Release Checklist

Purpose

This page is for NIST OSCAL Team members to know how they perform quality checks on releases as we follow our branch, version, and release guidance. This page documents for staff how to quality check a release from the appropriate release branch before it is merged and tagged as ready.

Hotfix Branches

You will apply one or more PRs targeting the release-X.Y branch so that you can add a bug fix, so for v1.0.9 you would use this method to fix a bug with high priority and not merge any new functionality by targeting release-1.0. At the end you would have release-1.0 branch be updated and tagged for v1.0.10 release.

• Before you start:

  • Clone the repository OR fetch the repository with git fetch --all.

• Build the artifacts from the current release:

  • Check out the current release tag:

    git checkout release-X.Y.    # This LATEST Major.miner release-X.Y branch should be created from the Latest release branch

  • Before you proceed, make sure your submodules are current with

    git submodule update --init --recursive

  • Build the artifacts to a temporary directory:

    cd build # Make your way to the OSCAL build/ dir
    make clean GENERATED_DIR=generated_LATEST_release # Ensure all old release artifacts have been deleted
    make all GENERATED_DIR=generated_LATEST_release   # Generate all artifacts to an ignored directory

• Build the artifacts for the upcoming release and compare to the previous release:

  • Check out develop

    git checkout develop

  • Before you proceed, make sure your submodules are current with

    git submodule update --init --recursive

  • Build the artifacts to a temporary directory

    cd build # Make your way to the OSCAL build/ dir
    make clean GENERATED_DIR=generated_NEW_release # Ensure any release artifacts have been deleted
    make all GENERATED_DIR=generated_NEW_release   # Generate all artifacts to an ignored directory

  • Diff the artifacts in generated_LATEST_release and generated_NEW_release

    • The Compare Folders Extension for VSCode can be used to compare the contents of two directories.
    • The diff tool (part of GNU DiffUtils) can compare the directories as well as individual files. Consult the documentation for details.

• Finalize the release, PRing develop into the current release branch:

  • Create PR(s) and with a target branch of release-X.Y, not main
  • Direct team members to review the PR, following the above steps to diff the artifacts.

• Post release (AFTER PR HAS BEEN MERGED)

  • Someone in the OSCAL Admin Team should follow post-release guidance for updating the main branch: https://github.com/usnistgov/OSCAL/blob/main/versioning-and-branching.md#releasing-a-patch-revision
  • (If applicable) Follow the documentation on OSCAL-Pages/CONTRIBUTING.md to perform a release of OSCAL Pages.
  • (Always) Trigger OSCAL Reference automation to rebuild the model documentation.

• Communicate release to the community.

  • Coordinate with the outreach director to take the release notes and publish them to the OSCAL Lobby community channel in Gitter.
  • Coordinate with the outreach director to take the release notes and publish them to oscal-dev@list.nist.gov and oscal-updates@list.nist.gov.
  • Update the news page with a PR to the news page on the content site and publish it. usnistgov/OSCAL-Pages#52 is a good example PR.

What do I look for in a quality check (QC)?

To be clear up front: there will be no exhaustive, detailed guidance on how to definitively spot a quality control issue when performing this final review. As you increase your experience with the codebase, the CI/CD automation, and their relationship in the release process, you will get a better sense for what is a potentially low-risk change and what is a potentially high-risk change. This section provides a high level overview.

What changes are often important?

1. Any addition, change, or removal of a part of the Metaschema modules
2. Any addition, change, or removal of a part of the schemas you cannot determine is directly linked to a change in 1
3. Invalid schemas generated from 1
4. Any addition, change, or removal of a part of the generated reference documentation for the models you cannot determine is directly linked to a change in 1
5. Generated catalogs and/or example content in the oscal-content repository (i.e. those not in the ./src directory) that doesn't validate against the JSON schemas or XML schemas

What changes are often not important?

1. Adding or removing individual spaces that are not in documentation strings of the Metaschema modules or schemas
2. Adding or removing blank lines to the Metaschema modules or schemas
3. Indentation of lines in the Metaschema modules or schemas with nearly identical syntax or content

FAQ

Why skip the profile specification resolution step when prepping a build?

Currently, the stylesheet template that generates each anchor id in HTML for each section of the specification in a <h3/> header will use the XSLT 1.0 generate-id() function. This function, per the specification, will generate a unique ID for the XML node (underlying the specification in the adjacent .specml file) but given the context of the document and tree changes the id in that position will change almost every run.