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 18F project varies widely, there are certain elements that should be present on every project. This document aims to detail those elements and provide suggested tools and resources.

Docker

We’re piloting Docker as a dependency management solution so that all developers can get started quickly. See our initial recommendations for using Docker for development.

Initialization Checklist

This list is aspirational, but a good place to start. Not all of these elements will apply to every project (e.g. visual regression tests don’t make sense for an API). We will try to include all in upcoming project templates; until then, do your best!

  1. Standard project files (consider using 18f init):
    1. LICENSE.md
    2. CONTRIBUTING.md
    3. README.md
    4. .about.yml
  2. .gitignore for your languages (though also consider a global config])
  3. Language version specification (e.g. .nvmrc, runtime.txt, Gemfile)
  4. Back end project files (e.g. setup.py, package.json, .gemspec) if creating a library
  5. package.json for front end apps
  6. Build scripts (e.g. grunt, rake, manage.py)
  7. Dependency descriptions (e.g. Gemfile, requirements.txt). Don’t forget to pin them
  8. Cloud.gov manifests (one per environment.) See the manifest_*.yml files in fec-cms for a great example
  9. .cfignore (can be a sym link to .gitignore to get started)
  10. Linter setup (straight flake8, rubocop, eslint)
  11. Unit test setup for each language
  12. Integration test setup (e.g. Selenium, Phantom)
  13. Pa11y setup
  14. Visual regression setup (e.g. Backstop)
  15. Continuous integration/testing (e.g. Travis, CircleCI)
  16. Code coverage metrics (e.g. CodeClimate, CodeCov, Coveralls). Aim for 90+%, worry if it drops below 80%.
  17. Static code quality tool (e.g. CodeClimate)
  18. Static security analysis as part of CI

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.

Commonly used project management tools:

Continuous Integration Service

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.

Pick a CI service with a GitHub integration so that the build status can be seen for each pull request.

Commonly used CI services:

Static Analysis Tool

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.

Commonly used static analysis tools:

Sandboxing and security

Developers needing to test their code live should use a cloud.gov sandbox or TTS-managed AWS equivalent.

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.