-
-
Save PierreRochard/dad65528025cfac21bc5521ef7e629ac to your computer and use it in GitHub Desktop.
Based on website traffic logs and positive feedback from frequent | |
contributors to Bitcoin Core, BitcoinACKs.com is already finding | |
"product/market fit", so I'm bringing it out of beta and releasing it as | |
version 1! | |
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 make that happen 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 then they will read through your code and leave comments. | |
Optionally they may actually compile your code and test its | |
functionality. | |
After a reviewer has provided their conceptual and code feedback on the | |
pull request, as the author 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 code changes in these pull requests overlap with your | |
own then 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 then merge in 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: | |
While this view does give a lot of information, it is not comprehensive. | |
For example, it does not display if 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: | |
There are additional product ideas I would like to implement | |
in future versions, which I've listed here: | |
https://github.com/PierreRochard/bitcoin-acks/blob/1.0.0/README.md | |
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 then 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 PRs 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. |
PierreRochard
commented
May 21, 2018
A tiny nitpick in the final paragraph:
...if maintainers can easily identify pull requests that are ready to be
merged then authors do not need to remember to...
Should probably have a comma after "merged".
Otherwise, LGTM. Thanks for building BitcoinACKs.com!
@harding fixed it, thanks for giving it a read!
Nice explanation and a great helpful initiative.
What I was missing when reading the first paragraph was some context, maybe this is given by the environment where this text will be published, otherwise a few lines explaining why this should be read are welcome.
Cheers!
@Quenos agree, I moved a sentence up as an intro
Loving this project. Two thoughts:
-
It actually seems like a dashboard of ACKs, maybe add a tldr at the top of the blog and/or an html <title> on the BitcoinACKs.com, "A bitcoin pull request dashboard", to make it easier for others to find when searching.
-
ACK is very terse, almost to a fault, maybe add a little blockquote/image at the top of the post as a refresher.