How do you balance speed of delivery and quality in your software development process? Add elimination of waste to the mix and you’ll never get bored. To find the right balance is about asking the right questions, asking them often, and experimenting. Inspired by Colloq’s blog post, I want to give you a quick run-down of our usage of GitHub tools.
The most prominent discussion (flame war?) around the three motivating factors for process change is the one about lowering quality to gain speed. Instead of out-right damning it, we really should mature to take it as what it is: one of the trade-offs that can be made in engineering. And since lowering quality really is about slowing down in the future, the discussion really should focus around those questions: How much speed do we need right now? Is it worth so much speeding up now, that we accept a much bigger slowdown in the future when this module will have to be rewritten or this API redesigned?
More interesting though is when waste enters the equation. Waste is the part of your process that does not increase neither speed nor quality. It’s just an unnecessary cludge on your feet, slowing you down.
To remove waste, we at engageSPARK experiment with and change our development process on a regular basis. A large part of our inspiration is from others, of course, and this week I was reading Colloq’s blog post The Tools We Use to Stay Afloat. We too use a couple of GitHub tools, and so I was happy to get both confirmation for the way we use some of our tools as well as new inspiration. In that spirit, I’ll share how we organize our work with GitHub.
The Obvious: Issues & Pull Requests
Unsurprisingly, we use issues and pull requests for their intended purpose. Still, I usually find that articles like the one from Colloq are at their best
when they dive into the gritty details of how exactly the tools are used. In case you agree, read on, otherwise skip to Projects.
GitHub Issues
We have about half a dozen GitHub repositories, with some subprojects inside. In each repository, we use issues to track bugs and discuss features for that code base. If a feature or bugfix requires changes in multiple repositories, then we put the main issue in a meta repository, which is just there to collect such parent issues and create specific implementation-focused issues in the individual code repositories.
Each issue has labels to determine the type (bug report or feature request) and state (Question, if it needs answers). In case of a bug report, labels indicate the severity (1-4), if the bug was found on the production system and if it was spotted by a customer.
We then use organization-wide searches to answer questions, such as: What issues wait on questions to be answered? How many severe (severity 1) open bugs do we have that are not assigned to a dev? For a quick example, see this search for all open bugs in the Python org on GitHub.
Managing Labels in Multiple Projects
One tedious detail about labels is that they are managed per repository. So, if you want to use the “Severity: 1” label in all your eight repositories, you need to create it eight times. And then you make a typo in one and wonder why your search does not work. Argh!
Yes, it’s a pain keeping labels consistent. Other people think so, too. And good thing they did something about it: Have a look at git-labelmaker. and git-label-cli. I’ve used the latter together with git-label-packages and that works like a charm.
Pull Requests
Each pull request (PR) references the issue it was created for. Its life-cycle is: Open, in review, merged/closed.
A PR is open as long as its developer is still coding on it. Each commit is automatically tested using Jenkins as CI. When the developer and Jenkins are satisfied, the label “needs-review” is added, since we require each PR to have at least one review, all of which must approve.
Reviews happen either next to each other on the screen or asynchronously with comments on the diff. After each review, the reviewer removes the label again, indicating that no one else needs to review it. After the reviewer is satisfied and approves the PR, the developer adds the “ready-to-merge” label, at which point QA can test and merge it.
Github Projects
Each developer has their own board, with at least two columns: “Backlog” and “Doing”, however they are named. Here are some examples:
When a PR is ready to merge, its issue is moved to the QA board for testing, merging and deploying.
It’s each developers responsibility to make sure that QA is aware of their issue (by adding it to their board),
as an issue is not done, unless it’s in production.
Finally, we’ve a ”High Priority Issue” board so we can put the spot light on particularly urgent issues during our daily standup. Since issues can be part of multiple boards, they still also go through the normal flow of developer’s board to QA board.
engageSPARK Enhancement Proposals
One other use-case for GitHub is our EEP repository, containing the engageSPARK Enhancement Proposals, a shameless rip-off of Python’s PEPs. An EEP consists of a Markdown file and comes in one of three variants: A technical design, a process description or an information.
EEPs are initiated and discussed by opening a PR, which at some point is merged, adding the file to the list of EEPs, indicating it’s now agreed upon. More on EEPs in another post.
Hopefully that was useful to you. If you’ve suggestions what we might try differently, let me know at muratk@!