Guides

Guides for working together, getting things done, programming well, and programming in style.

Our guides are heavily influenced by thoughtbot guides. If our guides do not cover your particular topic, review their guides for guidance.

High level guidelines

• Be consistent.
• Don't rewrite existing code to follow this guide.*
• Don't violate a guideline without a good reason.
• A reason is good when you can convince a teammate.

A note on the language

• "Avoid" means don't do it unless you have good reason.
• "Don't" means there's never a good reason.
• "Prefer" indicates a better option and its alternative to watch out for.
• "Use" is a positive instruction.

Guides by category

• General

Collaboration

• Code Review
• Terminology
• Working Together

Languages

• HTML
• Ruby
• SQL-dbt
• Typescript
• Terraform

Frameworks and platforms

• Rails
• React
• Testing with RSpec
• Testing with Jest

Protocols

• Authorization
• Data Changes
• Feature Flags
• Object-Oriented Design
• Web Monitoring

Testing

• Automation

Recommended Editor / IDE Setup

• VSCode

Tools

• Git
• GraphQL
• PostgreSQL

Other

• AWS
• Kubernetes
• Recommended Reading
• Responsibilities & Rituals
• Tools
• Publishing Gems with GitHub Packages

*Rewriting with tools

An exception to the guideline "Don't rewrite existing code to follow this guide" is that when making a change that a tool such as Rubocop or TSC can automatically fix, allow it to. This avoids unnecessary warnings in editors with integration with these tools.

When updating with a tool that can autofix, follow up with a commit to add the SHA of the autofix commit to each project's .git-blame-ignore-revs file. Note that these must occur in separate commits and that the SHA in the second commit needs to be updated if the first commit is rebased. This can be done in one Pull Request if you do rebasing manually or can be done as a follow-up Pull Request as well. See this blog post for details on why this is necessary.