This page is for potential contributors to the OSCAL project. It provides basic information on the OSCAL project, describes the main ways people can make contributions, explains how to report issues with OSCAL, and lists pointers to additional sources of information.
The approach we’re taking with OSCAL is agile. We’re adopting the philosophy of implementing the 20% of the functionality that solves 80% of the problem. We’re trying to focus on the core capabilities that are needed to provide the greatest amount of benefit. Because we’re working on a small set of capabilities, that allows us to make very fast progress. We’re building the features that we believe solve the biggest problems, so we’re providing the most value.
We track our current work items using GitHub project cards. The active project is typically the lowest numbered open project within the previously referenced page.
The OSCAL project is producing several types of deliverables, including the following:
- Schemas for the OSCAL component models
- Schematron definitions, which are basically an extension of the XML schemas that provide more validation capabilities
- XSL templates for production of human-readable versions of OSCAL XML content
- CSS, so people who are developing catalogs and profiles using XML tools can use CSS for data entry, which offers a much more usable interface
- Documentation to define the OSCAL component models, capture the operational model of how to use OSCAL, and explain how you can convert existing content (catalogs, profiles, etc.) into OSCAL formats
Contributions are welcome in any of these areas. For information on the project's current needs and priorities, see the project's GitHub issue tracker (discussed below). Please refer to the guide on how to contribute to open source for general information on contributing to an open source project.
All requests for changes and enhancements to OSCAL are initiated through the project's GitHub issue tracker. To initiate a request, please create a new issue. The following issue templates exist for creating a new issue:
- User Story: Use to describe a new feature or capability to be added to OSCAL.
- Defect Report: Use to report a problem with an existing OSCAL feature or capability.
- Question: Use to ask a question about OSCAL.
Issue triage is managed by the core OSCAL project team using a specialized project board.
The core OSCAL project team regularly reviews open issues, prioritizes their handling, and updates the issue statuses and comments as needed.
There are two mailing lists for the project:
- [email protected] for communication among parties interested in contributing to the development of OSCAL or exchanging ideas. Subscribe by sending an email to [email protected]. To unsubscribe send an email to [email protected].
- [email protected] for low-frequency updates on the status of the OSCAL project. Subscribe by sending an email to [email protected]. To unsubscribe send an email to [email protected].
Contributions can be made to the following branches in this repository:
- release-*: The release branches are used to provide patches to a major or minor version of OSCAL. The branches are named release-major.minor. You should provide changes only to the highest numbered minor release for a given major release. Patch releases are made more frequenly than major or minor releases.
- develop: This branch is used to queue changes for the next major/minor release of OSCAL. A major/minor release will result in the creation of a new release branch, once the development has been completed and the update is to be staged for release.
More information about how releases are managed in this repository can be found in the versioning and branching guide.
The OSCAL project uses a typical GitHub fork and pull request workflow. To establish a development environment for contributing to the OSCAL project, you must do the following:
- Fork the OSCAL repository to your personal workspace. Please refer to the Github guide on forking a repository for more details.
- Create a feature branch from the main branch for making changes. You can create a branch in your personal repository directly on GitHub or create the branch using a Git client. For example, the
git branch workingcommand can be used to create a branch named working. - You will need to make your modifications by adding, removing, and changing the content in the branch, then staging your changes using the
git addandgit rmcommands. - Once you have staged your changes, you will need to commit them. When committing, you will need to include a commit message. The commit message should describe the nature of your changes (e.g., added new feature X which supports Y). You can also reference an issue from the OSCAL repository by using the hash symbol. For example, to reference issue #34, you would include the text "#34". The full command would be:
git commit -m "added new feature X which supports Y addressing issue #34". - Next, you must push your changes to your personal repo. You can do this with the command:
git push. - Finally, you can create a pull request.
- Please allow the NIST OSCAL maintainers to make changes to your pull request, to efficiently merge it, by selecting on your fork the setting to always allow edits from the maintainers.
- Review the OSCAL release and versioning strategy and choose the base branch accordingly. Normally, you should target the
developbranch or arelease-x.yas the base branch unless asked to use a different branch. Please select the appropriate branch before requesting a review from a maintainer so delays in approving your pull request are avoided.
This repository consists of the following directories and files pertaining to the OSCAL project:
- .github: Contains GitHub issue and pull request templates for the OSCAL project.
- json: Provides OSCAL JavaScript Object Notation (JSON) schemas and utilities that can be used to convert content in other OSCAL formats to OSCAL JSON-based formats.
- xml: Provides OSCAL Extensible Markup Language (XML) schemas and utilities that can be used to convert content in other OSCAL formats to OSCAL XML-based formats.
- docs: Stores sources for the OSCAL website.
- content: This directory once stored XML, JSON, and YAML content examples. These examples have been moved to the OSCAL content GitHub repository.
- build: Contains a collection of scripts, eXtensible Stylesheet Language Transformations (XSLTs), and other artifacts used to support this repository's continuous integration and continuous deployment (CI/CD) processes.
- src: This includes the resources used by the NIST OSCAL Team to manage OSCAL development, including the metaschema files used to maintain the OSCAL models across all supported formats. This directory once stored source artifacts used to produce the XML, JSON, and YAML resources that were provided in this repository. These resources have been moved to the OSCAL content GitHub repository.
- CODE_OF_CONDUCT.md: This file contains a code of conduct for OSCAL project contributors.
- CONTRIBUTING.md: This file is for potential contributors to the OSCAL project. It provides basic information on the OSCAL project, describes the main ways people can make contributions, explains how to report issues with OSCAL, and lists pointers to additional sources of information. It also has instructions on establishing a development environment for contributing to the OSCAL project and using GitHub project cards to track development sprints.
- LICENSE.md: This file contains license and copyright information for the files in the OSCAL GitHub repository.
- USERS.md: This file explains which types of users are most likely to benefit from consuming available OSCAL tools and content.
The NIST OSCAL team is using the GitHub project cards feature to track development sprints as part of the core OSCAL work stream. A typical development sprint lasts roughly a month, with some sprints lasting slightly less or more to work around major holidays or events attended by the core project team. The active sprint is typically the lowest numbered open project within the previously referenced page.
Each development sprint consists of a set of user stories, that represent features, actions, or enhancements that are intended to be developed during the sprint. Each user story is based on a template and describes the basic problem or need to be addressed, a set of detailed goals to accomplish, any dependencies that must be addressed to start or complete the user story, and the criteria for acceptance of the contribution.
The goals in a user story will be bulleted, indicating that each goal can be worked on in parallel, or numbered, indicating that each goal must be worked on sequentially. Each goal will be assigned to one or more individuals to accomplish.
Note: A user story that is not part of a specific development sprint can still be worked on at any time by any OSCAL contributor. When a user story is not assigned to sprint, its status will not be tracked as part of our sprint management efforts, but when completed will still be considered as a possible contribution to the OSCAL project.
The project cards for each sprint will be in one of the following states:
- "To do" - The user story has been assigned to the sprint, but work has not started.
- "In progress" - Work has started on the user story, but development of the issue has not completed.
- "Review in Progress" - All goals for the user story have been completed and one or more pull requests have been submitted for all associated work. The NIST team will review the pull requests to ensure that all goals and acceptance criteria have been met.
- "Reviewer Approved" - The reviewers have confirmed that all goals and acceptance criteria have been met.
- "Done" - Once the contributed work has been reviewed and the pull request has been merged, the user story will be marked as "Done".
Note: One or more pull requests must be submitted addressing all goals before an issue will be moved to the "Review in Progress" status. If any goals or acceptance criteria have not been met, then feedback will be provided as comments in the user story and the issue will be returned to the "In progress" state.
A primary goal for this repository is to be transparent in the development work we do. Providing regular updates on issue progress is important in achieving this goal. Each OSCAL contributor needs to provide periodic status updates on issues for which they have made progress on. This status will be reported as a comment to the associated issue. For a user story that is part of an OSCAL development sprint, status reports will typically be made before the close of business the day before the weekly OSCAL status meeting (typically held on Thursdays).
When reporting status, it can be useful to identify any areas that are causing difficulties or if specific decisions needed to be made by one or more individuals. To identify a specific individual for action, use "@user" to reference the individual who needs to respond to the issue. This will ensure that the individual is updated with this status.
To clone this repository, use the following command:
git clone --recurse-submodules https://github.com/usnistgov/OSCAL.git
This GitHub repository makes use of Git submodules to mount other repositories as subdirectories.
The command above handles initializing submodule as part of the clone. To do this seperately when cloning this repo for the first time, you need to initialize the submodules that this repository depends on. To do this you must execute the following command:
git submodule update --init
Some clients will make use of Git over SSH with a private SSH key for GitHub projects. For convenience, the submodules are configured to use HTTP instead of SSH. To override this default behavior, you will need to configure your Git client to use SSH instead of HTTP using the following command:
git config --global url."[email protected]:".insteadOf https://github.com/
This instructs your Git client to dynamically replace the HTTP-based URLs with the proper SSH URL when using GitHub.
Submodule contents will be periodically updated. To ensure you have the latest commits for a configured submodule, you will need to run the following command:
git submodule update --init --recursive