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..ad8c832 --- /dev/null +++ b/new_project/readme.md @@ -0,0 +1,106 @@ +# 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 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 + +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 provides more detail about specific guidelines for the candidate +open-source software project. + +## 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 + +Software projects should not include any nonpublic (sensitive) information. Nonpublic +information in this instance is any information that has not previously been published. +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 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 + +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.