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.
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.
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!
- Standard project files (consider using
.gitignorefor your languages (though also consider a global config])
- Language version specification (e.g.
- Back end project files (e.g.
.gemspec) if creating a library
package.jsonfor front end apps
- Build scripts (e.g.
- Dependency descriptions (e.g.
requirements.txt). Don’t forget to pin them
- Cloud.gov manifests (one per environment.) See the
manifest_*.ymlfiles in fec-cms for a great example
.cfignore(can be a sym link to
.gitignoreto get started)
- Linter setup (straight
- Unit test setup for each language
- Integration test setup (e.g. Selenium, Phantom)
- Pa11y setup
- Visual regression setup (e.g. Backstop)
- Continuous integration/testing (e.g. Travis, CircleCI)
- Code coverage metrics (e.g. CodeClimate, CodeCov, Coveralls). Aim for 90+%, worry if it drops below 80%.
- Static code quality tool (e.g. CodeClimate)
- 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
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.