Project Setup
While the specific setup for each TTS project varies widely, there are certain elements that should be present in all source code repositories. This document aims to detail those elements and suggest corresponding tools and resources.
Source code management
TTS projects use GitHub for source code management, with their repositories under a government-owned organization.
- GitHub Standard
Repository Checklist
Below is an aspirational list of configuration and files for a source code repository. Not all of these elements will apply to every project (e.g. visual regression tests don't make sense for an API).
-
-
LICENSE.md
Standard -
CONTRIBUTING.md
Standard -
README.md
Default
-
-
.gitignore
(though also consider a global config) -
Programming language version specifications (e.g.,
.nvmrc
,runtime.txt
,Gemfile
) -
Dependency version descriptions (e.g.,
Gemfile
,Pipfile
,package.json
) — don't forget to pin them -
Build scripts
-
Unit test setup for each programming language
-
Docker
- Dockerfiles
- Compose files
- .dockerignore
-
cloud.gov/Cloud Foundry
- Manifests, one per deployment environment (e.g., 18F/fec-cms, 18F/culper)
.cfignore
(can be a symlink to.gitignore
to get started)
-
Deploy scripts
-
Accessibility scanning (e.g., Pa11y Default )
-
Integration test setup (e.g., Selenium Suggestion )
-
Visual regression setup (e.g., Backstop Suggestion )
Branch protection Requirement
Set up branch protection rules for each repository. The most current ATO checklist requires it; it's also a good practice to prevent mistakes like an accidental force-push to main.
We recommend at the very least enabling:
- Require pull request reviews before merging
- Restrict who can push to your main branch
Please refer to GitHub's branch protection documentation to help determine what other configuration settings are best for your project.
By default, protected branch rules do not apply to people with admin permissions to a repository, allowing admins to merge PRs without an external review when necessary.
Project Management Tool
Every project, no matter the size, should use a project management tool to keep track of ongoing tasks and to do items. The project management tool should be linked to somewhere in the project's GitHub repository so that others can find it easily.
Choose a tool that will work for you and your partner. Remember, they will be the ones using it once the engagement is over!
-
GitHub Issues Default
-
Trello Suggestion
-
Jira Suggestion
Continuous Integration/Continuous Deployment
Developers don't always remember to run the test suite. That's why we have Continuous Integration services to run the tests automatically after each commit. CI also helps ensure there's nothing specific to the developer's machine that makes the tests pass.
A Continuous Deployment service allows a development team to receive rapid feedback on new features or bug fixes. CD also helps ensure deployment and infrastructure issues are identified earlier in a release process, and are scoped to a smaller number of changes.
Pick a CI/CD service with a GitHub integration so that the build status can be seen for each pull request.
-
CircleCI Default
-
GitHub Actions Suggestion
Code coverage metrics
Aim for more than 90% of your source code to be covered by tests; worry if coverage drops below 80%. For repositories with multiple programming languages/components (e.g., front and back ends), ensure that coverage reports are aggregated and reported on the entire project, in addition to reports on individual components.
- Code Climate Quality Suggestion
Static analysis for code quality
A good code review process is essential to writing good code. But certain code problems are difficult for humans to spot. Duplication, for example: if new code is an exact duplicate of code from an existing file in a project, that might not be caught in a code review. Static analysis tools catch duplication, security concerns, and more. Also see Static Security Analysis.
-
CodeQL on GitHub (for security analysis) Default
-
Code Climate Quality (for maintainability metrics) Suggestion
Dependency management
Applications require specific versions of programming languages, libraries, databases, services, and configuration to execute. A dependency management solution helps abstract that complexity and makes it easier for cross-functional teams to create consistent, reproducible, local development environments.
- Docker Suggestion
See our Docker for Development recommendations.
Deployment infrastructure
Developers needing to deploy their code beyond their local environment should use either:
-
a cloud.gov sandbox Standard
-
a TTS-managed AWS sandbox account Standard
-
or Federalist (for static web sites) Standard
Caution
The use of tools such as localtunnel
and ngrok
, which make your locally running services visible to the internet,
are not allowed because they present a large security concern. Consult
#infrastructure
on Slack for any questions.