Release Prep

Summary

This page is to instruct developers on how to use Github to build a release of FedRAMP artifacts for publication. This page documents standard operating procedures that conform with ADR 2 on the release strategy and versioning procedures.

Common Scenarios

Publish a Release

• Create a new milestone with Github by accessing github.com/GSA/fedramp-automation/milestones/new.
• Review the relevant issues associated with the release and confirm work is complete and associated pull requests have been successfully merged. Link additional issues with work completed, but were not properly tracked against this milestone.
• Determine the updated version number to create a release branch.
  • For significant changes ony applicable to GSA/fedramp-automation, and not sub-modules or transitive dependencies, that introduce major breaking changes, increment the major version number (i.e. x in fedrampx.y.z-oscal1.0.0).
  • For changes only applicable to GSA/fedramp-automation, and not sub-modules or transitive dependencies, that introduce feature enhancements without major breaking changes, increment the minor version number (i.e. y in fedrampx.y.z-oscal1.0.0).
  • For bug fixes to GSA/fedramp-automation, and not sub-modules or transitive dependencies, that fix bugs without any feature enhancement or breaking change, increment the patch version number (i.e. z in fedrampx.y.z-oscal1.0.0).
  • Additionally, if the OSCAL sub-module dependency will be updated, ensure the -oscalx.y.z suffix is updated to reflect this new version (i.e, ensure any update to the sub-module matches the x.y.z version number in the official NIST OSCAL release used in the update like fedramp1.1.2-oscalx.y.z)
• Create a release branch from the code in the master branch on your developer workstation.
  • git clone [email protected]:GSA/fedramp-automation.git
  • git checkout -b release/fedramp1.1.2-oscal1.0.0 # follow the guidance above, this is a notional example
• Review the code and CI/CD builds for accuracy and integrity.
• Use Github to create a tag associated with this branch by accessing github.com/GSA/fedramp-automation/releases/new.
  • Set the target to the relevant branch.
  • Write a release summary.
  • Publish the release when it is ready for publication.

Validations: Publish End of Sprint Draft Release

• Check or create an issue, as appropriate in the relevant project for the 18F fork in github.com/18F/fedramp-automation/issues/new.
• Check the link or add the link for this issue to the relevant sprint milestone in github.com/18F/fedramp-automation/milestones.
• Prepare a sprint branch with an easily identifiable name with master or an appropriate source branch, e.g. releases/sprint-N.
• Create a pull request to from the 18F fork to the GSA upstream repo by accessing github.com/GSA/fedramp-automation/compare.
• If not automatically assigned to repository admins, manually assign PR review to @GSA/fedramp-automation-admins.
  • Consult with that team and ensure code is merged before the end of the 10x ASAP sprint cycle.
• After merge, resync the 18F fork with git or use the Fetch Upstream function accessible on the repo landing page by accessing github.com/18F/fedramp-automation.

Upgrade OSCAL Version for FedRAMP Repository Artifacts

• Open a tracking issue with Github by accessing github.com/GSA/fedramp-automation/issues/new
• If applicable, link this issue to the proper milestone by accessing github.com/GSA/fedramp-automation/milestones. See general release guidance above.
• Create an issue branch from the code in the master branch on your developer workstation.
  • git clone [email protected]:GSA/fedramp-automation.git
  • git checkout -b issue-XYZ-update-oscal # follow the guidance above, this is a notional example
  • (cd fedramp-automation && git submodule update --init --recursive && git push origin HEAD)
  • (cd fedramp-automation/oscal && git checkout v1.1.0) # 1.0.0 is chosen as a notional example
  • If applicable, build the dev tools container (cd fedramp-automation/vendor/oscal/build && docker build --build-arg "saxonversion=9.9.0-1" --build-arg "hugoversion=0.69.2" --build-arg "calabashversion=1.3.2-100" -t oscal:latest .) # change dependency parameters as appropriate per NIST OSCAL guidance
  • Run the container in interactive mode: (cd fedramp-automation && docker run -it -v $(pwd):/oscal oscal)
    • Validate the updated content in the container docker run -v $(pwd):/oscal oscal -c "./vendor/oscal/build/ci-cd/validate-content.sh -o ./vendor/oscal -a . -c ./src/config"
    • Make necessary modifications in src directory until no schema validation errors are returned.
    • Convert XML sources into JSON and YAML docker run -v $(pwd):/oscal oscal -c "./vendor/oscal/build/ci-cd/copy-and-convert-content.sh -o ./vendor/oscal -a . -c ./src/config -w . --resolve-profiles"
    • Make necessary modifications in src directory until no conversion errors are returned.
    • Exit the dev tools container.
• Once this work is complete, follow the general SOP for publishing a release above, appropriately incrementing the -oscalx.y.z suffix.