Contributing to OSCAL development and maintenance

Contributing to the OSCAL Schemas, Documentation and Examples/Content Development and Maintenance

OSCAL Main Repositories

• Core OSCAL repository - where OSCAL metaschema definition files and schemas in XML, JSON and YAML are maintained
• OSCAL content repository - where OSCAL examples and NIST SP 800-53 catalog and profiles are maintained
• OSCAL pages repository - where the majority of the OSCAL website is maintain
• OSCAL reference repository - where the OSCAL references are dinamyccally generated from the metaschema definition files

NIST team maintains other repositories related more or less to the OSCAL. A complete list can be found at https://github.com/usnistgov

Branching

The main branches of OSCAL repository are listed below. Similar branching approach is used in all the repositories, but for the sake of brevity, we include below only links to the core OSCAL repository

• main contains the current supported, production-ready release.
• develop contains the current set of development changes for the next release. New features can be contributed to this branch.
  • This branch is an integration branch where development code can be tested prior to promoting the code to a release.
  • This branch will be used to create a release-major.minor branch when the developed code is ready to be staged for release.
• nist-pages contains the currently deployed website content, which is managed by the CI/CD process.
• release-* branches, where * matches a MAJOR.MINOR version number, are used to support patch releases for a major or minor version of OSCAL. You should provide changes only to the highest numbered minor release for a given major release. Git Setup

To use this strategy, the following Git configuration is needed:

All contributions work must be done in a personal fork of the OSCAL Git repository.

git remote add upstream git@github.com:usnistgov/OSCAL.git

Branching for contributors

Personal Working Branches

All individual work will be done in branches in a personal fork of this repository.

Personal branches should be named using the convention <issue #>-brief-dashed-name.

Once work is complete on a personal branch, the branch should be interactively rebased to tidy any commits. Then a PR should be opened against the target feature-* branch or the develop branch if the changes are to be included in the next release.

For more information on how to do this, please refer to our contribution guide.

Branching for repository maintainers

Release Branches

A release branch is used to stage code in preparation of a new release. Refinements to code can be made in a release branch in preparation for a new release.

Release branches represent production-ready code that is near-ready for release.

VERY IMPORTANT:

• Name a release branches release-MAJOR.MINOR, e.g. release 1.0, release 1.1, release 2.0
• Branch release branch off of develop.
• Merge the release branch back into develop as releases are made.
• Merge the release branch back into main to reflect the latest release

Creating a Release Branch

A release branch can be created by issuing the following Git commands:

git checkout -b release-1.2 develop
# TODO: need a method to bump version numbers in metaschemas and content
git commit -a -m "Bumped version number to 1.2"
git push --set-upstream upstream release-1.2

Releasing a Release Branch

Once the release is ready, the release can be made using the following Git commands:

git checkout main
git merge --no-ff release-1.2
git tag -a 1.2.0
git push --follow-tags

Releasing a PATCH Revision

Patch releases for a given MAJOR.MINOR version will be marked by annotated tags. This allows the same release branch to be used for multiple PATCH releases.

Once a patch release is ready, the release can be made using the following Git commands:

git checkout main
git merge --no-ff release-1.2.1
git tag -a 1.2.1
git push --follow-tags

Feature Branches

A feature branch provides means to integrate a set of features that are a work in progress and the release target of a given set of features is unknown or unpredictable. Work on such a set of features can proceed independent of work targeted at the next release in develop.

Feature branches represent major development topics.

• Branched off of develop.
• Merged back into develop when the feature work is completed.
• Feature branches will be named feature-*, where the * is a brief dash-separated label describing the feature.

VERY IMPORTANT:

• If multiple committers are working on a feature, then each committer must work in a personal branch and submit a PR to the feature branch when their work is complete.

Creating a Feature Branch

A feature branch can be created by issuing the following Git command:

git checkout -b feature-NAME develop
git push --set-upstream upstream feature-NAME

where feature-NAME will follow the pattern feature-*.

Syncing a Feature Branch with develop

It may be necessary to periodically sync a feature branch with the latest in develop. You can do this using the following Git commands:

# switch to the feature branch
git checkout feature-NAME
# get the latest from upstream
git pull --ff-only upstream feature-NAME
# get the latest from develop
git pull -r upstream develop
git push --force-with-lease upstream feature-NAME

Merging a Feature Branch

The following Git commands will be used to merge a feature branch into develop:

# switch to the develop branch
git checkout develop
# merge the feature branch
git merge --no-ff feature-myfeature
# delete the feature branch once it is merged
git branch -d feature-myfeature
# push the branch to the upstream repository
git push upstream develop