Conventions

• Use factories in feature tests. Avoid them in unit tests.

  Rationale: factories allow you to build objects while omitting irrelevant details. These make specs more readable and robust against unrelated changes, but hides complexity. For features, this tradeoff is good; we want the spec to read like a description of the intended behavior without any irrelevant stuff in it. For unit tests, this tradeoff is bad; we want to see precisely what our dependencies are and how we expect them to behave.

• Feature branches with arbitrary naming convention.

• We use Trello for scheduling high-level work. For actual feature work, use Github issues. It's okay if there's some redundancy, and there's no need to cross-reference, but if there's lots of context, keep the bulk of it in Github and link back to Trello where appropriate.

  Rationale: Github issues are easier to reference from commits and pull requests, but Trello's UI makes time clearer. [mrdomino says: I don't know about this one. I'd prefer to keep everything in one place, but I don't want to force Trello links in commit messages.]

• Commit messages should be one of the following formats:

  One-line description <50chars wide ({wip,fixes} #issue)
  

  One-line description <50 characters wide
  
  Detailed description using markdown syntax, lines <72 characters wide
  except for links.
  
  Fixes #issue.
  

  For small commits, or those that are part of longer feature branches, there's no need to include an issue number reference.

• Docs will live on the wiki for the most part.

• TODO comments loosely follow the KJ style guide: # TODO(type): description where type is:

  • now: fix before git push
  • soon: fix before next release
  • someday: nice to have some day, but no urgency
  • perf: possible performance enhancement
  • security: possible security concern
  • cleanup: maintainability improvements with no user-visible effects
  • spec: something that needs better testing
  • other types, where appropriate (add them here)

• Infinite line length for outside-of-code documentation, prose, and non-human-readable text. 80-column limit for code except where it's annoying to do so.

  Rationale: mrdomino likes to have a terminal open next to his browser, and has a small-ish laptop display. Code generally looks terrible when auto-wrapped, but English text is easy to auto-wrap.

• Code review is great, do lots of it. Use Github pull requests and get review for anything significant. It's okay for small changes to go straight to master without review though.

• Use squash-and-rebase from Github's pull request UI. Don't create explicit merge commits.

  Rationale: in most UIs, the contents of merge commits are invisible even if they are non-trivial (i.e. if there were conflicts.) It's very easy and common to botch merges, leading to mysterious situations where you thought you did a feature, the history shows you did the feature, but the feature isn't present in master. With squashed commits, history is just a sequence of diffs without any funny business.

• Don't let any of the conventions get in your way. If following a convention impedes your progress, just break the convention.