There are many ways to measure if your team is doing good. There’s the Joel test or maybe you can measure story velocity (don’t do that).
What I was missing though, was a simple quantitive way to measure a few simple things about how we wrote code. I believe this is a good first step, once past that hurdle, well, then merge conflicts will be reduced and reviews will be easier and thereby better.
There are two main contributors to this, pull request size and how long they live.
Measure units of work
It’s easy to look at each PR coming out and say “that’s too big, break it down” and that’s definitely a good step forward. I felt though, that I wanted to see that this actually got better, without looking at every single PR. What I wanted was a bit of a system, statistics, a simple overview.
Work Work Stats
Because of this, I created Work Work Stats, hosted at https://workworkstats.app/. Really it is nothing fancy, just a simple Angular app that will look at your account, what organisations and repositories you’re part of and allow you to pull together a team and look at the overall stats for this team.
What about Github contributor stats
Well, that’s exactly what it is, it’s contributor stats. Not team stats. Often, teams work across several repositories which may have contributors outside the team as well. I have found both now and in the past that I want to measure on a given number of repositories and members. I want to make sure my part of the team can measure our improvements without others affecting the data. Now, I’m encroaching on dangerous ground here I know, I don’t want it to become a competition of speed of PRs or committed lines of codes.
Statistics are not everything
Please, please, remember, when using this tool that statistics are just numbers. They don’t reflect the truth. They’re only one side of a coin. One point of view. One line of code may take three days to get out, it all depends on the problem. However, statistics do tell a story. If pull requests are open for a week and several hundred lines of code long. Well, that’s telling a story too, one that you shouldn’t brush off with an “it’s only numbers” explanation.
So what are good numbers?
I was happy to find that there were lots of forerunners I could refer to in terms of keeping pull requests small. Take for example this great post on The anatomy of a perfect pull request. Very simple, keep it under/between 200-400 lines of code. Well, the smaller the better but no bigger than that.
As for how long a pull request should be open? I haven’t researched there but I always say “a merge a day keeps the conflicts away”. (yes, you’re allowed to scorn me for that rhyme, but it sticks)
It’s hard to get a PR done, reviewed and merged within a day though but I figure if it’s done in a day, perfect! If it is merged within 3 days, it’s not horrible. Anything above that, well, then you’re asking for trouble.
Visualising improvement
In Work Work Stats I’ve tried showing the improvement as a way to motivate the team. In the UI it’s easy to go into Team Stats and week-by-week or even each morning just show the numbers, it’s going up! Or down!
Caveats with the current version
I think you’ll get confused even on the first page, like, why am I asking you both to log in and give to provide a personal access token?
Well, here is a list of all the slightly strange things that are in there right now:
- You can use a personal access token or oauth login to read your repositories, or both. This allows you to read out repositories from your organisations without having to have the org allow you to do so (using your access token, only read rights are required)
- You have to log in/provide access token each time you access the site, I don’t have any storage and I don’t want to keep your secrets in local storage
- A team consists of repositories and members from one organisation, so when you click your organisation and add a repository, that’ll wipe anything from another organisation
- To check team stats, click your organisation, search for a repository and add it to the team, then you can go into the repository and toggle members for the team
- I do keep your team in local storage, there shouldn’t be anything too secret in there, it’s just a list of repos and members
I’m sure I have forgot stuff so if you find something else, let me know and I’ll add it in here, or better yet, fix it.
Check it out
I’m happy to add more features if it’s useful to you. There’s so much that could be done and so little time but if there are more people using it that’s a huge inspiration to continue working on it.