This document captures some important project practices that we employ. If you want to contribute to Matterhorn, for best results, please follow these practices.
Many of the practices described below are really about serving some overall concerns:
master branch should be stable enough to be release-ready at
all times. This promise helps us be agile in the event of a need to
do an unplanned release.
develop branch is where development occurs.
New feature development begins and stays on a new feature branch,
feature/FEATURENAME, until it is declared stable
enough to be merged. Once more testing of a feature is needed,
especially in concert with other work, it should be merged to
develop has been deemed stable enough to release, it can be
When a feature branch implementation is complete, before merging to
develop we do a code review that is appropriate to the level of
complexity and risk of the work being merged, which may involve an
in-person code tour but typically involves just commit review with
questions and requests for changes. We do this to ensure that other
team members are aware of the ramifications of the work, to provide
an opportunity for feedback, and to get fresh eyes on the work to
spot problems that won’t be evident to its author.
Bug fixes and other small, uncontroversial changes can be committed
master and merged back into
develop. This ensures
that bug fixes are not held up by other development work in case a
bugfix release is desired.
We use the GitHub issue tracker for user bug reports and feature requests, and to capture our own intentions about planned and potential work.
We use milestones to group tickets for big efforts, such as server compatibility releases or planning cycles.
When creating issues, we try to make issues as actionable as possible
when the scope and details are well-understood, but this isn’t always
possible. If we can’t be concrete about what a ticket entails, we
assign the label
high-level to indicate that more team discussion
or context-gathering will be required before a concrete plan can be
made. We also use the label
high-level to indicate any ticket with
insufficient detail that needs further discussion before we can
When planning big efforts, we strive to get team alignment on the scope of planned efforts. Creation of a ticket does not necessarily mean that we have gotten team alignment or settled on scope. The appropriate scope will be a function of time and availability, pragmatism, feature parity with upstream, motivation, etc.
When doing refactoring that may be risky or touch a lot of the program, we strive to break the job down into a sequence of incremental changes that each produce a working program and ultimately get us where we want to be.
When planning new work, we strive to get input from the team before the work begins, rather than after it is completed, to reduce waste and to ensure that the work is well-informed. The bigger or more impactful the change, the more important this is - and it applies to work done in spare time as well as at work.
If resources allow, consider pair programming as a means of tackling bigger, cross-cutting problems. Although it costs more in terms of person-hours, it can be a very effective technique for producing better designs with fewer bugs and more mind-sharing.
For experimental work or new features, consider “prototyping” or “throwaway coding,” in which the first implementation of a new feature is intended to be discarded upon completion. Rather than producing code, the result of this is the learning that occurs when exploring a design. Then, having learned, one can embark on a better-informed implementation.
We would like issues not to linger too long unaddressed, because then the meaning of “open ticket” is ambiguous to us and to end users: is it planned? Is it well-understood? It’s unclear.
But we can only tackle so many things, and sometimes we don’t even know enough about what’s involved in a task to know its level of effort. So in the mean time, before we can investigate, the ticket lingers.
Once we’re learning what is inovlved, using the ticket as a place to hash out ideas or collect context is annoying because using ticket comments for that isn’t effective.
To address these concerns:
On this page we’ll collaboratively hash out design ideas, collect context and research, and share approaches. These documents represent a “staging ground” for new ideas.
Once enough context has been gathered to support moving forward on the feature, create concrete tickets from the context. It’s also possible we decide not to move forward, in which case the rationale for aborting can be clearly captured on the wiki. This way, external users can see why we decided not to implement something.
When external users create tickets for high-level features that cannot be implemented immediately but that we agree deserve consideration and need further investigation, close the tickets by referring to the newly-created context wiki page where we’ll be hashing out the details. This means that we strive to ensure that open tickets are by definition always workable and fleshed-out.
This way, when external users stop by to ask about features, we can point them at those pages to make it easier to 1) share the developed context, 2) make it clear what is missing in case they want to help, and 3) keep a record of design decisions for posterity even after the feature is implemented.