From a2ab5106d704e73ea316e0a8559fbf8b161879c3 Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Wed, 2 Aug 2023 12:12:09 -0400 Subject: [PATCH] [skip ci] Clarify guidance for usnistgov/OSCAL#1864. (#1869) --- CONTRIBUTING.md | 9 ++------- versioning-and-branching.md | 2 ++ 2 files changed, 4 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0a553b4736..c1cdebe3f8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,12 +31,7 @@ We track our current work items using GitHub [project cards](https://github.com/ ## Contribution options -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 +The OSCAL project is producing several types of deliverables, organized into several GitHub repositories as explained [in the project page](https://pages.nist.gov/OSCAL/about/projects/). 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](https://opensource.guide/how-to-contribute/) for general information on contributing to an open source project. @@ -73,7 +68,7 @@ The OSCAL project uses a typical GitHub fork and pull request [workflow](https:/ 1. Create a feature branch from the main branch for making changes. You can [create a branch in your personal repository](https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/) directly on GitHub or create the branch using a Git client. For example, the ```git branch working``` command can be used to create a branch named *working*. 1. You will need to make your modifications by adding, removing, and changing the content in the branch, then staging your changes using the ```git add``` and ```git rm``` commands. 1. 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"```. -1. Next, you must push your changes to your personal repo. You can do this with the command: ```git push```. +1. Next, you must push your changes to your personal fork repo if you are individual community contributor, or optionally from this repository directly if you are a staff member on the NIST OSCAL Team. You can do this with the command: ```git push```. 1. Finally, you can [create a pull request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/). - 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](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork). - Review [the OSCAL release and versioning strategy](./versioning-and-branching.md) and [choose the base branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request) accordingly. Normally, you should target the `develop` branch or a `release-x.y` as 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. diff --git a/versioning-and-branching.md b/versioning-and-branching.md index b5fbacc1d5..fb24a36b09 100644 --- a/versioning-and-branching.md +++ b/versioning-and-branching.md @@ -60,6 +60,8 @@ git remote add upstream git@github.com:usnistgov/OSCAL.git ## Personal Working Branches +Staff on the NIST OSCAL Team can do work on branches in this repository or choose to do work as an individual outside contributor in a fork as described below. + All individual work will be done in branches in a personal fork of this repository. Personal branches should be named using the convention `-brief-dashed-name`.