Skip to content
This repository has been archived by the owner on Apr 12, 2024. It is now read-only.

Latest commit

 

History

History
147 lines (112 loc) · 8.35 KB

project-setup.md

File metadata and controls

147 lines (112 loc) · 8.35 KB
Raw
title sidenav sticky_sidenav
Project Setup
tools
true

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 {%include components/tag-standard.html %}

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 {%include components/tag-suggestion.html %})
  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 {%include components/tag-default.html %})
  16. Integration test setup (e.g., Selenium {%include components/tag-suggestion.html %})
  17. Visual regression setup (e.g., Backstop {%include components/tag-suggestion.html %})

Branch protection {%include components/tag-requirement.html %}

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 {%include components/tag-default.html %}
  • Trello {%include components/tag-suggestion.html %}
  • Jira {%include components/tag-suggestion.html %}

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 {%include components/tag-default.html %}
  • GitHub Actions {%include components/tag-suggestion.html %}

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:

{%include components/tag-caution.html %} 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.