Development Process

Small Issues

Smaller, one-off issues that don't require careful coordination and planning can just be created as an issue. Please tag them with relevant tags!

Large Projects

What constitutes a large project? This is somewhat subjective; there's no hard and fast rule for what needs a technical specification (tech spec) or not. In general, if you're going to expect it to be more than three distinct issues, it probably needs a tech spec. If in doubt, feel free to discuss it with the team.

1. Tech Spec Writing

A project starts off with a tech spec, where one or more members join forces to scope out the project and what it would take to implement it. This is done via GitHub Discussions, where there is a template with various prompts to consider when scoping it out. The goal of the tech spec is to ensure that there is no ambiguity when it comes to how the system will be designed, how the feature will be rolled out, and how it will be implemented at a high level. Doing so reduces the chances of mid-project pivots, where efforts are wasted and engineers frustrated.

Said differently: A technical specification exists to guide implementation and to clear any ambiguity around what needs to be done in order to ship a project.

Some tips:

• The level of detail should be enough so that people won't be wondering how something will be done from a high level, but it shouldn't be so much that the tech spec is basically doing the entire project.
• When writing technical documents, err on the side of brevity. Say just enough to get your point across.
• When writing tech specs, err on the side of decreasing scope instead of increasing scope if faced with the two choices.
• Not every section requires a response. Just leave N/A under a section if it's not applicable.

2. Tech Spec Review

Once written a tech spec should be reviewed by the team, where team members will ask clarifying questions, suggest alternatives (though the ones writing the spec should try to evaluate all options to avoid thrash). During this time, the tech spec may be edited, which is normal during this process.

3. Ticket Creation

Once approved, the tech spec authors will then break the tech spec into smaller, individual pieces of work, called "Tickets". Tickets are created as GitHub issues, and specify what the task itself is, alongside any dependencies. It also specifies "Acceptance Criteria", or AC for short, which is a list of statements that, when all of which are true, is an indicator that the job is done.

When trying to decide how far to break down tasks, try to make it so that:

• Work that unblocks further work is made as small as possible (i.e. if you have a task that allows 2+ other tasks to start development, that task should be its own ticket).
• The task is a coherent piece of testable code.
• It can be reasonably finished, reviewed, and merged within a week.

4. Development

Once tickets are created, it's off to the races with development! See the GitHub Workflows page for more guidelines on how to take on tasks.