Skip to main content
U.S. flag

An official website of the United States government

Dot gov

The .gov means it’s official.
Federal government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a federal government site.

Https

The site is secure.
The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.

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.

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).

  1. Community profile
  2. .gitignore (though also consider a global config)
  3. Programming language version specifications (e.g., .nvmrc, runtime.txt, Gemfile)
  4. Dependency version descriptions (e.g., Gemfile, Pipfile, package.json) — don’t forget to pin them
  5. Build scripts
  6. Unit test setup for each programming language
  7. Linter setup (e.g., flake8, rubocop, eslint Suggestion )
  8. Docker
  9. cloud.gov/Cloud Foundry
  10. Deploy scripts
  11. Continuous Integration/Continuous Deployment
  12. Code coverage metrics
  13. Static analysis for code quality
  14. Static security analysis
  15. Accessibility scanning (e.g., Pa11y Default )
  16. Integration test setup (e.g., Selenium Suggestion )
  17. Visual regression setup (e.g., Backstop Suggestion )

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.

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.

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.

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.

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.

Deployment infrastructure

Developers needing to deploy their code beyond their local environment should use either:

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.