This page is for potential contributors to this project. It provides basic information on the project, describes the main ways people can make contributions, explains how to report issues relating to the project and project artifacts, and lists pointers to additional sources of information.
This project uses an agile approach for development, where we focus on 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, this allows us to make very fast progress. We’re building the features that we believe solve the biggest problems first to provide the most value. We provide extension points that allow uncovered cases to be supported by others.
We track our current work items using GitHub project cards in the project's work board.
Contributions of code and documentation are welcome to this repository.
For more 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 the repository 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 the project.
- Defect Report: Use to report a problem with an existing feature or capability.
- Question: Use to ask a question about the project or the contents of the repository.
The project team regularly reviews the open issues, prioritizes their handling, and updates the issue statuses, proving comments on the current status as needed.
This project uses a typical GitHub fork and pull request workflow. To establish a development environment for contributing to the project, you must do the following:
- Fork the repository to your personal workspace. Please refer to the Github guide on forking a repository for more details.
- Create a feature branch from the
mainbranch 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, thegit 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 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 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 documentation files pertaining to the project:
- .github: Contains GitHub issue and pull request templates, and GitHub action workflows for the project.
- CODE_OF_CONDUCT.md: This file contains a code of conduct for all project contributors.
- CONTRIBUTING.md: This file is for potential contributors to the project. It provides basic information on the project, describes the main ways people can make contributions, explains how to report issues, and lists pointers to additional sources of information. It also has instructions on establishing a development environment for contributing to the project and using GitHub project cards to track development sprints.
- LICENSE.md: This file contains license information for the files in this GitHub repository.
- USERS.md: This file explains which types of users are most likely to benefit from use of this project and its artifacts.
All other files and directories are related to the Java code managed in this repository.
This project is using the GitHub project cards feature in the project's work board to track development as part of the core project work stream.
Development is done against a set of user stories, that represent features, actions, or enhancements that are intended to be developed. 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. Each user story is organized against a developmental milestone, indicating the release for which the user story is planned to be addressed.
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 milestone can still be worked on at any time by any project contributor.
When working on a goal that is part of a user story you will want to provide a periodic report on any progress that has been made until the user story's goal(s) have been completed. This status is reported as a comment to the associated user story issue. Progress on goals in each issue will be tracked by the repository maintainers and will be used to update the project cards for the current sprint.
When describing any open issues encountered use an "@mention" of the individual who needs to respond to the issue. This will ensure that the individual is updated with this status. Please also raise any active, unresolved issues on the weekly status calls.
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" - All reviews of a pull request related to a user story have been completed. The pull request still needs to be merged.
- "Done" - Once the contributed work has been reviewed and the pull request has been merged, the user story will be marked as "Done".
Note: A pull request must be submitted for all goals before an issue will be moved to the "under review" status. If any goals or acceptance criteria have not been met, then the user story will be commented on to provide feedback, and the issue will be returned to the "In progress" state.
This project originated as part of the Open Security Controls Assessment Language (OSCAL) program. We use the OSCAL communications channels for this project as well.
A Gitter chat room is available for OSCAL-related discussions. This is a great place to discuss issues pertaining to this work with the community. The NIST OSCAL team actively chats on the OSCAL Gitter. This room is also setup with Github integration, which provides a good summary of recent Github repo activities within the chat room.
There are two OSCAL mailing lists, which are also used for this project.
- OSCAL Developer List: [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].
- OSCAL Updates List: [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].
This project is in the worldwide public domain.
This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.
All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.