Hacker News Reader

Comment by no_protocol | Hacker News Reader

> fix the problem yourself and submit a pull request

For smaller projects out on GitHub I often see attempts at this that fail. Stuck in "Open" status for years or outright rejected.

Maybe the account in control of the canonical repository is no longer active or interested in the project.

Maybe that person doesn't understand or agree with the submitted code or asks for more accompanying work.

Maybe the submission is under-documented or not even fully understood by the submitter.

Each of these types of sticking points can be overcome, but the bottom line is they all take a lot of work from one side or the other.

Does anyone have examples to share of open source projects that have very low friction for drive-by contributions while still maintaining quality? Projects with very clear documentation and instructions for contributing? It would be nice to have some models to aspire to.

View on HN

> For smaller projects out on GitHub I often see attempts at this that fail. Stuck in "Open" status for years or outright rejected.

This is why you fork.

Some forks even merge branches that were PR'd to the original fork and just start managing their own.

This is why GitHub has a "network" graph where you can see the other forks on the timeline and can choose a newer fork if an older one has either been abandoned or is not being upkept or doesn't work with some newer version of X that you need it to work with.

> Does anyone have examples to share of open source projects that have very low friction for drive-by contributions while still maintaining quality? Projects with very clear documentation and instructions for contributing?

Yes, absolutely. Read https://rfc.zeromq.org/spec:42/C4/.

We developed the C4 contract (in the form of an RFC) precisely to teach maintainers how to welcome new contributors while keeping quality high. It took many years to refine this approach. By formalizing it, it becomes really simple for projects to adopt: all you need in your README 'Contributing' section is a license (we recommend MPLv2), a link to this RFC, and later a style guide to ensure consistent code style.

The thing about C4 is that it teaches people to make small testable patches, and to trust new contributors. We know from experience that it's users of a project who keep it alive. Original authors and core maintainers burn out, get full time jobs, start new projects. As long as you have users, though, you have potential contributors.

Small patches, merged immediately, with reviews and improvements made asynchronously over time. This style is lovely to work with, kills bike shedding (we argue with new patches rather than comments), and reduces the friction in the project to as low as possible.

More on optimistic merging: http://hintjens.com/blog:106

In terms of friction: we aim to get a patch live on master within a few minutes. If that breaks master, we fix it either with a new patch, or a revert. Anyone can submit a patch, anyone can revert or improve previous patches. You can't merge your own pull requests. We work straight on master so new code is pushed aggressively towards users capable and willing to use it (those who build off master). We use CI heavily to test backwards compatibility, i.e. that existing APIs and protocols haven't broken.

There is also a whole theory of how incremental testable patches remove the need for "intelligent design" and thus the dependency on brilliant key individuals. That's another story which I cover in my book "Social Architecture". Free to read online if you want it.

Best of all, this process works. We know because we've been using it quietly and successfully in the ZeroMQ community for years.

Of all the things I've done in open source, I consider this my most important work, as it solves the really essential problem raised in TFA, which is how to keep open source projects alive over the long term.

Thanks Pieter!

I've been interested in that optimistic merging idea of yours for a while now, but I've never had the courage to pull the trigger on it anywhere myself.

I had a few questions about it though. The process seems to work by moving the code review portion after the merge instead of doing it before the merge. So instead of sitting in a review queue, the code goes live, and if there's any problems the code is removed. I was wondering if this is really that much better from the contributer's POV. Sure it's discouraging if they submit a patch and have it ignored, but it must be even more discouraging to submit a patch, have it accepted, and later have it removed because it wasn't good enough.

Also, I know the incremental patch style is the style for OM, but is there any way to do large sweeping changes, other than forking the project or trying to break it into a series of incremental changes?

How well does OM scale with number of contributors? Have you any experience with very low numbers of contributors (where I think you could potentially have bad patches sit in the repo for an excessive period until they are removed), or with very, very large numbers of contributors?

Really though, all the ZeroMQ RFCs are great. If any of you are doing some C programming, I'd highly recommend checking out ZeroMQ's CLASS C style guide: https://rfc.zeromq.org/spec:21/CLASS

Like any radical shift in technique, it's best to try on a small project. It takes a while to get the hang of it. I'll answer your questions...

- It is really seldom that a patch is reverted (that a patch is removed). As in, it only happens in exceptional cases, when someone has made an obviously toxic patch by accident on on purpose. It's far easier to move forwards with improvements to the patch. We encourage people to do this rather than provide opinions on the code in writing. What this does is interesting: it brings others in the project into the work, and creates instant mentor-mentee hookups. We see this really often and it is a wonderful thing. You make a patch, it's merged, someone sends a patch on your patch and explains why, and suddenly you have someone in the project who knows that area and can teach you.

- Large sweeping changes are sometimes the simplest way to e.g. refactor some code. It's usually a Really Bad Idea to make functional changes at the same time. It also depends a lot on the language. I'd disrecommend large sweeping changes to a C project, absolutely. The risk of introducing multiple bugs is just too high. In a scripted language, far less risk, and so it's safer. In general, functional changes appear to work better as many small testable steps, and refactoring can work as a single mass change.

- OM scales really well. It needs 2+ people in the project. After that, the limits are elsewhere. Projects with hundreds of contributors are probably too large in terms of internal structure. It means you get ad-hoc pseudo-projects inside a single repository which means poor internal contracts, etc. I'd say a project with more than 7-10 active contributors at any time is getting too large. IME a network of small projects works far better than larger monolithic projects.

- I use OM (the C4 protocol) on all projects, whether they are just starting (my first act is then to call for co-maintainers), or have been around for ages (like the libzmq C++ core library, with hundreds of contributors). We've never seen an issue of scale.

Cheers!

;-)

No, quite different. There are strong rules about what constitutes a valid patch. Probably stronger than in most projects.

GitHub really needs a way to mark a project as abandoned and possibly point to a maintained fork.

Looking at the last commit date is something of a proxy for that.

Sure, you have to meet the coding guidelines and rules of the project. Many won't accept a drive by pull request without a unit test and documentation for example. 9 times out of 10 the project authors are grateful for the help.

Reply on news.ycombinator.com