Last active
May 21, 2018 20:17
-
-
Save PierreRochard/dad65528025cfac21bc5521ef7e629ac to your computer and use it in GitHub Desktop.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. |
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.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
@harding fixed it, thanks for giving it a read!