From 8073a4eb16f7d4531325ad470bc7e3c9d5054d64 Mon Sep 17 00:00:00 2001 From: derrick chambers Date: Thu, 11 Mar 2021 13:49:25 -0800 Subject: [PATCH 1/5] add review instructions and template --- new_project/approval_template.md | 23 +++++++++ new_project/readme.md | 88 ++++++++++++++++++++++++++++++++ 2 files changed, 111 insertions(+) create mode 100644 new_project/approval_template.md create mode 100644 new_project/readme.md diff --git a/new_project/approval_template.md b/new_project/approval_template.md new file mode 100644 index 0000000..3204224 --- /dev/null +++ b/new_project/approval_template.md @@ -0,0 +1,23 @@ + + +# Opensource Review: {project_name} + + +- [ ] code has been approved by a member of @policy_reviewers +- [ ] code has been reviewed by a member of @technical_reviewers +- [ ] code has been reviewed by a member of @security_reviewers diff --git a/new_project/readme.md b/new_project/readme.md new file mode 100644 index 0000000..afe5bfb --- /dev/null +++ b/new_project/readme.md @@ -0,0 +1,88 @@ +# Github Release Process + +This directory delineates the process, guidelines, and requirements for releasing +new projects to the [niosh-mining github page](https://github.com/niosh-mining). + +# Pre-Review Requirements + +Before starting the github release approval process, please ensure the candidate code satisfies the +following requirements: + + 1. The code is stored in a git repository + 2. The repo does not include any [sensitive data](#Data) (consider removing old history). + 3. The repo includes [documentation appropriate to the maturity of the software](#Documentation). + 4. The code includes a [testing procedure](#Testing). + 5. The code includes an [OSI approved open-source liscense](https://opensource.org/licenses). + 6. The code includes a [version string and a versioning system](#Versioning) + 7. The code has been uploaded to the niosh-mining github page as a **private** repo. + +# Initiating a Review + +After the requirements mentioned in this document are met, open a new issue in the +candidate repo (which is still **private**) entitled "Open Source Review". Copy the +contents of the [open_source_approval template](approval_template.md) as the body of +the issue and follow the directions and checklist. + +# Guidelines + +The following provide more details about specific guidelines for the candidate +open-source software projects. + +## Documentation + +The amount/type of appropriate documentation can vary widely based on the type/function +of the software and its maturity level. At a minimum, a readme file should be included +which includes the following: + + * The purpose of the software. + * An indication of the software's maturity (eg alpha, beta, etc.) + * A link to the [NIOSH about page/disclaimer](https://github.com/niosh-mining/about). + +You should also strongly consider adding the following: + + * Instructions for installing the software + * Instructions for contributing to the software + * Quickstart guides/examples + * Technical references + +when it makes sense to do so. + + + +## Testing + +Testing is essential to ensure software functions as intended. Best practice is to +develop a suite of automated tests which can be used to help vet proposed code changes, +guard against bug regression, and test dependency compatibilities. However, it is not +always feasible to develop an extensive suite of automated tests (especially for highly +graphical applications). In these circumstances, clearly defined instructions for running +manual tests should be included. + +## Data + +Generally, software projects should not include unpublished research data. Never +include any sensitive data . If data need to be included, +for example to enable testing, it is best to use anonymized, fictitious, or public data. + + +## Versioning + +Recommended versioning is largely based on [semantic versioning](https://semver.org/) +consisting of four components: + +[a.b.c.d] + +where: + +[a] is the Major Version. This number is set by application stakeholders and IT development based on the major feature set and design of the software. + This would include compatibility breaking changes. + +[b] is the Minor Version. Set by stakeholders and IT development based on incremental improvements and feature enhancements to the core application design. + This would also include larger bug fixes. + +[c] is the Revision of the software. Typically this number represents the quantity of times a release has been deployed to a production environment (or public download) + This typically would include minor bug fixes. + Note that all internal formal documentation, approvals and published help documentation or other writings will list [a.b.c] as the version number for the release. + +[d] is the (optional) Build Number. This number is set internally by IT development and is based on configuration and build changesets. + It is used by IT development for internal testing purposes and to match specific source repository changes to when a build occurred. From 670d6ccbfc55d79851fd9397dec8735d8b6a6b2a Mon Sep 17 00:00:00 2001 From: shawnboltz <73495214+shawnboltz@users.noreply.github.com> Date: Mon, 15 Mar 2021 09:29:34 -0700 Subject: [PATCH 2/5] Update readme.md Expanded on data that shouldn't be included in a repo. --- new_project/readme.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/new_project/readme.md b/new_project/readme.md index afe5bfb..6a7df7b 100644 --- a/new_project/readme.md +++ b/new_project/readme.md @@ -9,7 +9,7 @@ Before starting the github release approval process, please ensure the candidate following requirements: 1. The code is stored in a git repository - 2. The repo does not include any [sensitive data](#Data) (consider removing old history). + 2. The repo does not include any [nonpublic (sensitive) data](#Data) (consider removing old git history). 3. The repo includes [documentation appropriate to the maturity of the software](#Documentation). 4. The code includes a [testing procedure](#Testing). 5. The code includes an [OSI approved open-source liscense](https://opensource.org/licenses). @@ -47,8 +47,6 @@ You should also strongly consider adding the following: when it makes sense to do so. - - ## Testing Testing is essential to ensure software functions as intended. Best practice is to @@ -60,10 +58,18 @@ manual tests should be included. ## Data -Generally, software projects should not include unpublished research data. Never -include any sensitive data . If data need to be included, -for example to enable testing, it is best to use anonymized, fictitious, or public data. - +Software projects should not include any nonpublic (sensitive) information. Nonpublic +information in this instance is any information that has not previously been published. +Examples incude, but may not be limited to: + - Personally identifiable information (PII) or other sensitive data, + - unpublished research data, + - data protected by a non-disclosure or other written agreement, + - data that may be considered trade secrets, + - user credentials, or + - system-specific information (ip addresses, ports, protocols, etc.). + +If data need to be included, for example to enable testing, it is best to use anonymized, +fictitious, or public data. ## Versioning From da2e3ca0a8a4076a4af235d0c3e01817813c4ab1 Mon Sep 17 00:00:00 2001 From: shawnboltz <73495214+shawnboltz@users.noreply.github.com> Date: Mon, 15 Mar 2021 09:30:54 -0700 Subject: [PATCH 3/5] Update readme.md Fixed formatting --- new_project/readme.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/new_project/readme.md b/new_project/readme.md index 6a7df7b..fc36dcf 100644 --- a/new_project/readme.md +++ b/new_project/readme.md @@ -8,13 +8,13 @@ new projects to the [niosh-mining github page](https://github.com/niosh-mining). Before starting the github release approval process, please ensure the candidate code satisfies the following requirements: - 1. The code is stored in a git repository - 2. The repo does not include any [nonpublic (sensitive) data](#Data) (consider removing old git history). - 3. The repo includes [documentation appropriate to the maturity of the software](#Documentation). - 4. The code includes a [testing procedure](#Testing). - 5. The code includes an [OSI approved open-source liscense](https://opensource.org/licenses). - 6. The code includes a [version string and a versioning system](#Versioning) - 7. The code has been uploaded to the niosh-mining github page as a **private** repo. + 1. The code is stored in a git repository + 2. The repo does not include any [nonpublic (sensitive) data](#Data) (consider removing old git history). + 3. The repo includes [documentation appropriate to the maturity of the software](#Documentation). + 4. The code includes a [testing procedure](#Testing). + 5. The code includes an [OSI approved open-source liscense](https://opensource.org/licenses). + 6. The code includes a [version string and a versioning system](#Versioning) + 7. The code has been uploaded to the niosh-mining github page as a **private** repo. # Initiating a Review @@ -34,16 +34,16 @@ The amount/type of appropriate documentation can vary widely based on the type/f of the software and its maturity level. At a minimum, a readme file should be included which includes the following: - * The purpose of the software. - * An indication of the software's maturity (eg alpha, beta, etc.) - * A link to the [NIOSH about page/disclaimer](https://github.com/niosh-mining/about). + * The purpose of the software. + * An indication of the software's maturity (eg alpha, beta, etc.) + * A link to the [NIOSH about page/disclaimer](https://github.com/niosh-mining/about). You should also strongly consider adding the following: - * Instructions for installing the software - * Instructions for contributing to the software - * Quickstart guides/examples - * Technical references + * Instructions for installing the software + * Instructions for contributing to the software + * Quickstart guides/examples + * Technical references when it makes sense to do so. From 20e87b38b177248664e8e69a0196494046b1ad51 Mon Sep 17 00:00:00 2001 From: shawnboltz <73495214+shawnboltz@users.noreply.github.com> Date: Mon, 15 Mar 2021 09:32:50 -0700 Subject: [PATCH 4/5] Update readme.md --- new_project/readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/new_project/readme.md b/new_project/readme.md index fc36dcf..449ebbd 100644 --- a/new_project/readme.md +++ b/new_project/readme.md @@ -68,7 +68,7 @@ Examples incude, but may not be limited to: - user credentials, or - system-specific information (ip addresses, ports, protocols, etc.). -If data need to be included, for example to enable testing, it is best to use anonymized, +If in doubt, it is probably better to exclude the information. If data need to be included, for example to enable testing, it is best to use anonymized, fictitious, or public data. ## Versioning From 2d078c6f4c6417bb5b0f09318564e0368dd0e4a9 Mon Sep 17 00:00:00 2001 From: GPCole Date: Mon, 5 Apr 2021 16:49:15 -0400 Subject: [PATCH 5/5] Update readme.md Howdy, I've made some edits and suggestions. I also agree with the comment I saw in the thread about having a clear process to have a process defined to accept, integrate, and release updated code. I'm also not quite sure how to word it, but do we want to maintain an "officially vetted" release along with a "latest beta" release so the Github community can help test? I don't think it belongs in this document, but if an official product ends up using this location as the main distribution point, we should still make sure it has a coversheet so it can be listing on our Mining website. --- new_project/readme.md | 32 ++++++++++++++++++++++---------- 1 file changed, 22 insertions(+), 10 deletions(-) diff --git a/new_project/readme.md b/new_project/readme.md index 449ebbd..ad8c832 100644 --- a/new_project/readme.md +++ b/new_project/readme.md @@ -9,12 +9,23 @@ Before starting the github release approval process, please ensure the candidate following requirements: 1. The code is stored in a git repository - 2. The repo does not include any [nonpublic (sensitive) data](#Data) (consider removing old git history). - 3. The repo includes [documentation appropriate to the maturity of the software](#Documentation). - 4. The code includes a [testing procedure](#Testing). - 5. The code includes an [OSI approved open-source liscense](https://opensource.org/licenses). - 6. The code includes a [version string and a versioning system](#Versioning) - 7. The code has been uploaded to the niosh-mining github page as a **private** repo. + 2. The code must not contain details or references to CDC software security controls or protections. + 3. The code must have a clean Fortify scan. + 4. The repo must not include any [nonpublic (sensitive) data](#Data) (consider removing old git history). + 5. The repo includes [documentation appropriate to the maturity of the software](#Documentation). + 6. The code includes a [testing procedure](#Testing). + 7. The code includes an [OSI approved open-source liscense](https://opensource.org/licenses). + 8. The code includes a [version string and a versioning system](#Versioning) + 9. The code has been uploaded to the niosh-mining github page as a **private** repo. + +# Obtaining Approval + +Once the code package has been prepared, official approval to make the private repo public must be obtained. Approvers include: + + 1. Team Leader + 2. Branch Chief + 3. Associate Director of Science (ADS) + 4. Division Director or Deputy Division Director # Initiating a Review @@ -25,8 +36,8 @@ the issue and follow the directions and checklist. # Guidelines -The following provide more details about specific guidelines for the candidate -open-source software projects. +The following provides more detail about specific guidelines for the candidate +open-source software project. ## Documentation @@ -60,15 +71,16 @@ manual tests should be included. Software projects should not include any nonpublic (sensitive) information. Nonpublic information in this instance is any information that has not previously been published. -Examples incude, but may not be limited to: +Examples include, but may not be limited to: - Personally identifiable information (PII) or other sensitive data, - unpublished research data, - data protected by a non-disclosure or other written agreement, - data that may be considered trade secrets, + - data that describes or references security controls or protections, - user credentials, or - system-specific information (ip addresses, ports, protocols, etc.). -If in doubt, it is probably better to exclude the information. If data need to be included, for example to enable testing, it is best to use anonymized, +If in doubt, it is better to exclude the information. If data need to be included, for example to enable testing, it is best to use anonymized, fictitious, or public data. ## Versioning