GSA / automate.fedramp.gov

Other
4 stars 2 forks source link

Describe use of SemVer to Support FedRAMP revisions #2

Closed david-waltermire closed 1 month ago

david-waltermire commented 1 month ago

This PR provides documentation around the wholistic versioning approach that will be used by FedRAMP to version guides; validations; use of OSCAL models; SP 800-53 controls, baselines, and assessment procedures; and other resources.

david-waltermire commented 1 month ago

Some comments on the choice of SemVer vs SchemaVer, both of which have been discussed with the FedRAMP community.

Tools produced by many different stakeholders are key to realizing a more automated FedRAMP future state. As we are focusing more on automation, we need an approach that signals when changes occur to the FedRAMP data approach that impacts tools.

Using SchemaVer, we would mostly be making ADDITION changes for updates to SP 800-53, OSCAL models, and validations, which I don't think is right from a stakeholder perspective. SemVer is better suited to indicate the significance of these changes on tools. Given SemVer's MAJOR.MINOR.PATCH, we want to signal changes that affect tools in MAJOR and MINOR revisions. Given SchemaVer's MODEL.REVISION.ADDITION, we would be signaling most of these changes in REVISION and ADDITION revisions. Thus, SemVer is better positioned to signal changes that impact tools vs SchemaVer.

Rene2mt commented 1 month ago

Related to our versioning strategy, we can add some details around our strategy for dependency / version pinning (especially as it relates to external resource).

For example, what are FedRAMP's plans when source NIST OSCAL catalog has patch, minor, or major releases? If FedRAMP strategy is to pin to NIST's version 1.1.*, we'd keep using 1.1.0 as other versions of the catalog (e.g., 1.1.1, 1.1.2, etc.) come out, but when NIST has a minor release of the catalog (e.g., 1.2.*) that we want to pin to, FedRAMP OSCAL would then upgrade and have its own minor release to signal the dependency upgrade.

We can document the high level strategy in future updates to the Release Strategy and Versioning page, and communicate pinned versions in the release notes for each tag.