Our approach

Project teams may vary, but across 18F engineering we aim for consistency around deployments, git etiquette, and similar workflow conventions.

Continuous integration & deployment

All Projects Standard

• Ensure that your project is running automated tests in CI. Successful test completion should be a requirement for deployment.
• Generally, CI should perform deployments. This ensures the deployments are repeatable and don’t rely on individual development environments. See our documentation on continuous deployment for details on how to set this up.
• Deployments should be zero-downtime, achievable through tools like Cloud Foundry's rolling deployment process.
• In addition to deployments after code change, we generally need to (automatically) re-deploy daily to ensure the running containers haven’t been tampered with (an ATO compliance requirement). See CircleCI’s “schedule” docs for details.

Git & GitHub Standard

Git is our version control system of choice and GitHub is our current repository platform, but how to use these tools can be spelled out in a bit more detail. Note that we are looking to consolidate this with our existing documentation on code review and example workflows.

Security Requirement

For best practices on protecting sensitive information, check out the TTS Handbook.

Enable two-factor authentication for your GitHub account. This is required for all TTS employees.

As part of the ATO process, we require any branches which trigger automated deployment be protected by passing CI and peer review.

Other considerations

Standard

• Default to public for new repositories. See our guidelines about open source for more detail.
• Enforce reviewer approval of pull requests against the main branch.
• We prefer branches over forks to ease internal collaboration. If your project has many outside contributors, consider forks instead.
• Keep your repository clean; delete merged branches and avoid committing files specific to your dev environment (e.g. .DS_Store).
• Consider signing commits with a GPG key

Suggestion

• When in doubt, use feature branches and gitflow as your branch naming scheme.
• Follow this guidance about good commit messages.
• Consider using Allstar to enforce consistent branch protection rules or to require commit signing on all repositories in your organization. For example, see the Allstar configuration that the cloud.gov team is using.

Code style

Standard Use an opinionated automated code formatter whenever possible. This saves teams from wasting time arguing about code style, and makes it easy to comply. Specific suggestions in the pages for each language.