BitcoinACKs.com v1 Release
Based on website traffic logs and positive feedback from frequent contributors to Bitcoin Core, BitcoinACKs.com has found product/market fit. So I'm bringing it out of beta and releasing it as version 1! Thank you to Justin Moen for contributing to this release.
Contributing to open source software does not begin and end with writing code. There is a collaborative process between contributors to ensure that the software and its codebase evolve in a satisfactory direction. Participating in this process is rewarding because contributors accomplish together much more than they could in isolation, both due to the division of labor and due to peer review of contributions.
Engaging in the collaborative process also has costs. For the Bitcoin Core development process specifically, contributions are peer reviewed by a number of volunteers before being merged. This means that your contribution, in the form of a pull request, must attract the time and attention of reviewers. The simplest way to get a review is reciprocity: you carefully review a few pull requests, and their authors will generally return the favor. That said, your pull request can attract reviewers on its own merits as well, with a description indicating an attractive level of engineering quality or ingenuity.
A reviewer may "NACK" a pull request without having read one line of code, because the description of the pull request itself indicates irremediable conceptual problems. If a reviewer is interested in your pull request, they will read through your code and leave comments. Optionally they will compile your code and test its functionality.
After a reviewer has provided their conceptual and code feedback on the pull request, you respond by either updating the code in your pull request or providing justifications. If the reviewer is satisfied with your responses then they "ACK" your pull request.
During the process of review, other pull requests are likely to get merged in. If the changes in these pull requests overlap with your own, your pull request goes from being "mergeable" to "conflicting". You as the author must manually reconcile the differences and reviewers check to see that the reconciling changes are appropriate.
When the maintainers of the project are satisfied that an appropriate number of reviews have resulted in ACKs, they merge the pull request.
There are a few points of friction in this process which I decided could best be addressed with an improved list of pull requests. Here is a screenshot of the default GitHub list of pull requests:
GitHub Pull Requests
While this view does give a lot of information, it is not comprehensive. For example, it does not display whether pull requests are mergeable or conflicting. Additionally, it is not customized to reflect information generated by the Bitcoin Core development process. We have the number of comments, but no summary of who has ACKed the pull request.
This lack of visibility means that authors, reviewers, and maintainers have to click into each pull request and skim the comments to understand the status of the pull request. This would be manageable for a dozen open pull requests, but there are currently 265 open pull requests. Lack of visibility reduces the productivity of everyone involved.
BitcoinACKs.com increases visibility by querying GitHub's API for pull requests and their comments, parsing those comments, and displaying the information in a visually useful manner. Here is a screenshot of the BitcoinACKs.com list of pull requests:
BitcoinACKs.com Pull Requests
There are additional product ideas I would like to implement in future versions, which I've listed here.
The main outcome I'm hoping to see with BitcoinACKs.com is fewer pull requests languishing in the backlog. Volunteers can't be "told" what to review and when, but if the cost of identifying targets for review is lowered, we can expect to see more reviews being produced. Likewise, if maintainers can easily identify pull requests that are ready to be merged, then authors do not need to remember to ask for a merge. Lastly, BitcoinACKs.com has search, sort, and filter features which allow contributors to explore historical pull requests as well as open ones. Better tooling is not a panacea, and there's no substitute for thoughtful engineering, but improvements at the margin can help an open source project maintain quality while steadily increasing the number of contributors.
“At Core, in order to be more productive, we need an additional layer on top of GitHub to manage the load of around 7 new pull request & 100 comments per day. bitcoinacks.com is on the right way to be that layer”
“Bitcoinacks is a really great tool to get an overview of the state of open PRs in the Bitcoin Core repo. It’s made my life as a contributor much easier and more efficient.”
“bitcoinacks.com is a helpful layer on top of Github for Bitcoin maintainers and reviewers. Having a quick view into priority, ACK count, mergeability, diff length, and other attributes makes figuring out what to review more straightforward. I’m excited to see how future features aid Bitcoin’s development process even more.”
“I do think it makes our whole process a bit more transparent to new contributors, since they are new to the project and might not have the time to catch up on everything. I hope that your site encourages contributors to participate in the review process.”
“bitcoinacks.com is great. It adds much need visibility into the rigorous Core review process.”
“bitcoinacks is great”
“bitcoinacks has been improving quite a lot over the past week or two”