The CDCGov organization on GitHub is designed for use by CDC programs to collaborate with open communities further CDC mission to protect America from health, safety and security threats, both foreign and in the U.S.
This is a collection of practices to help programs design projects and collaborate with diverse communities looking to find, use, and contribute to open science.
We designed these practices to be intuitive, helpful, and evolving based on program and community input. Some practices are required and some are recommended. For required practices, projects that don't adhere to them will be contacted by administrators to help them meet the practices. Projects that habitually fail to meet these practices will be archived or made private. That has never happened, but we want to make sure CDC's projects are usable.
If you would like to use GitHub for your CDC project, please fill out this Office 365 Form. This will require your CDC login, so if you don't have a login, please find someone who does and ask them to request on your behalf.
GitHub is a third party web application used by CDC to collaborate with the public. Official CDC health messages will always be distributed through www.cdc.gov and through appropriate channels.
If you would like to create a new project, please complete this Form requesting access and confirming you have completed training on our rules of behavior.
Note that any source code used within CDC systems must comply with all cybersecurity processes prior to production use, including static and dynamic scanning. The state of source code stored on GitHub is independent from, and usually varies, from the built code used in production systems.
If you need support with your project, please submit an issue to the template repo, or send an email to mailto:data@cdc.gov.
If you are interested in using GitHub for non-open source projects, please check out our enterprise organization CDCent or search for "GitHub Enterprise" on the CDC intranet.
- Obtain clearance from your organization prior to setting up and publishing a repository. Until you have completed clearance, include clear language in your repo indicating the current status, something like "As a first step, this document is under governance review. When the review completes as appropriate per local and agency processes, the project team will be allowed to remove this notice. This material is draft."
- Set a meaningful project name, description, and topics to improve discovery and use of your project. For AI-related projects, the Code.gov Implementation Guidance to Federal Agencies Regarding Enterprise Data and Source Code Inventories must be followed when setting topics.
- Add a readme.md file at the root with a description of your project, the team responsible for the project. This should help users understand how to setup and use your project.
- Assign an open source license based on program need. For guidance on licenses, please review the article, "Open Source Development for Public Health Informatics", refer to existing CDCgov projects, or ask for consultation support in choosing a license.
- Include the required notice sections in your readme.md to comply with relevant CDC policies and procedures, adapt as necessary based on your program need.
- Include a description of your development process in the readme.md file, if your project is not active, mark it as archived to help users understand that it is not an active project.
- If active, enable GitHub automated security alerts and configure notification for the repo admin to see and respond to these alerts in a timely manner. Projects that do not respond to security alerts will have issues raised in their project by admins and may be archived to protect users.
- Never commit sensitive information, including usernames, passwords, tokens, PII, PHI. Use pre-commit tools like Clouseau to systematically review material before committing.
- Enable issues to allow for administrative and automated issues related to their project.
- Respond to issues and PRs created by admins in a timely manner. Ignored issues on your project will result in archiving or deletion.
- Agree on project conventions and include them in your readme.md. Depending on what type of project, this includes folder structure for data, linters, editor configuration (eg, MicrobeTrace's .editorconfig). This will help improve the quality of your project and make it easier for others to contribute to your project.
- Describe support and community procedures. CDC does not provide warranty or official support for open source projects, but describing how you would like questions and issues will assist users of your project. If you use a wiki, or project board, or package manager, describe and link to that.
- Include references to publications, presentations, and sites featuring your project.
- Add an entry to open.cdc.gov to the data, code, api, or event page to help people find your project on cdc.gov
- Add versions and tags describing major releases and milestones. For example, open.cdc.gov's releases each time a new version is published to the web site or geneflow's changelog.
- Follow Semantic Versioning 2.0.0 when creating versions for your project.
- Describe and test reproducible practices to install and build your project. For example, injury_autocoding's code section on running the project's scripts).
- Recognize contributors and existing resources that have helped the project. For example, fdns-ms-hl7-utils' AUTHORS file.
- Automate build and test procedures to reduce the effort of outside contributors to send pull requests (eg, Travis CI, Circle CI, GitHub Actions)
- Establish pull request templates to make it easier for contributors to send pull requests. For example SDP-V has a checklist for each PR to match their development practices.
- Appropriately gather metrics on how your project is used and incorporate this into your feature planning process.
- Incorporate documentation into your development cycle, and where possible, automate the generation of documentation so it is more likely to be up to date and useful to people interested in your project.
This checklist was adapted from the CDC IT Guard Rail and put here to help people who don't have access to the intranet.
- Create a new project using the template repo.
- Update your readme.md following the CDC GitHub Practices for Open Source Projects
- Choose a license. Most projects are ASL2, but license should meet public health program need. See https://www.philab.cdc.gov/index.php/2012/03/27/open-source-development-for-public-health-informatics/ for more info on choosing a license.
- Remove all sensitive info.
- Talk with your ADI, ADS, and ISSO for review and clearance.
- After approval, create a GitHub user.
- Fill out the Request a Repo form for a new repo on CDCGov or CDCai.
- When you get an email or push alert that your repo is ready, push to GitHub
- Keep your project up to date, when you're finished flag it as archived.
We welcome any feedback and ideas for how to make these practices more useful. Please submit ideas using the built-in issues function of this project.
Many existing projects and resources helped us create this set of practices.
- CFPB Open Tech
- TTS Engineering Practices Guide
- 18F Open Source Policy and Practicing our open source policy
- GitHun and Government: How agencies build software
- code.gov
- Federal Source Code and Open Source Toolkit
- Federal Source Code Policy (M-16-21)
- openCDC
- CDC/ATSDR Policy on Releasing and Sharing Data
- Digital Services Playbook