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.

> 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.

> it's your duty ...

> it's your responsibility ...

If open source project owners owe people exactly nothing, then certainly open source project users have neither the duty nor the responsibility to contribute anything back, either.

The duty and responsibilities given to users are real.

If you want help from a project maintainer to fix your submitted issue you have a duty to provide them enough information to solve it.

If your project has a dependency on a library it's your responsibility to your own code to make sure that proposed fixes work.

I don't think you understand what a "duty" is. A duty is an ethical and moral requirement. Creating the conditions for someone else to help me most easily is not a duty; it's just common sense.

The vast majority of open source projects are a volunteer effort. Either you contribute and better the software or support its community, or you don't. But if you choose the latter you can't complain about the software.

I certainly can complain about the software. Obviously everyone else is free to ignore me.

Even though I use all of their software, I honestly don't care about the Linux, Java, Node, Emacs, or Python "communities" and it is frankly silly for open source developers to expect me to. I have real communities and responsibilities to devote unpaid labor to.

I hate to say this, but most of the time, I just fork it, fix it, and forget it.

That may sound like I'm not being a good community member. But, most of the time, dealing with the maintainers is more effort than I have time for.

> I just fork it, fix it, and forget it.

When you say you like to just fork it, do you mean that you're publishing the fixes you make somewhere, or just keeping them to yourself?

I am very interested in any attempts at some kind of fork aggregator (see [0] and [1]) that can help interested parties see what patches have landed in each fork, rather than just which ones have their own users.

[0]http://forked.yannick.io/jquery/jquery

[1]http://www.toddsifleet.com/projects/github-forks#jquery/jque...

Most of my projects are forked by people who never make any changes to the fork. I'm not sure if this is some kind of spam or people trying to make GitHub profiles look better to recruiters.

A fork = code under the user's control. A fork doesn't go away if the original source does.

GitHub's UI makes unintentional forking quite easy. When it shows a button like "Fork: 25", clicking the "25" will show the forks (which I often want), clicking "Fork" will perform a fork (which I usually don't want).

These types of forks are asirational guitars bought by people who want to spend the time but never find it.

Agreed. For me, forking is like super starring. Ive starred over 1000 repos, but hv forked < 100.

>When you say you like to just fork it, do you mean that you're publishing the fixes you make somewhere, or just keeping them to yourself

Really depends, some maintainers and authors really dislike forking, they also tend to be the ones hardest to deal with on pull requests.

This is so true and so sad. It's what kills many projects: maintainers who think they have some holy mandate for "quality" and create such a difficult environment for new contributors that we fork the project instead.

Read my longer comment in this thread about the C4 process and imagine: you send a patch, and it's merged onto project master within half an hour, and you can then depend on it being available to you forever, as long as you invest in some documentation and tests (if it's a new feature).

I tend to do something similar, but I always at least open an issue/PR (depending on the amount of work I did on the fork) and just list the things I did, why I did them, and some useful docs/links that can help someone pick up where I left off.

on multiple occasions I've gotten emails about PRs I made and self-closed with someone thanking me for the start of the general solution, and that finished it up and made it into a full PR.

Sure, OSS can have bugs and I understand authors don't owe me anything. It would be nice if the program can be improved, but I'm certainly not going to demand it. Depending on the software and problem sometimes I can fix it, and when I have fixed it, I'm happy to submit a patch, if there's a reasonably convenient way to do so.

I have encountered times when it's more complicated to offer the fix than it was to fix the problem. IMHO, it would be useful to be able to send code and documentation without having to navigate multiple layers of logins, subscriptions, and other hurdles.

Sometimes the bug is too obscure for me to find, or requires deep knowledge of hardware/OS interfaces beyond the capacity of mere mortal users. Like patches, bug reports should also be easy and uncomplicated to submit, and to communicate about if necessary.

I think many users are sophisticated enough about software in general, and want to help resolve problems. They may not be able to single-handedly debug complex issues but when met halfway by projects these users would probably do a lot more to assist.

An open source project is as good as dead without users. Whether they are complaining or not, if someone gives you a piece of their valuable time, that should be appreciated.

Users are only as good for the project as their reinvestment in the project. A small number of users who contribute code, money, or bug reports is better than a large number of users who never interact with the maintainers. In most cases the number of overall users is correlated with the number of contributors, but it's the latter group who are driving development and growth. A large user base is more a side effect of a successful project than a driving force.

may be, you are right, users are as good as their reinvestment, with regards to open source. However, reinvestment doesn't necessarily have to mean code, money, bug reports or something similar. It could be as simple as, spreading the word. I really appreciate those who share their experiences with a project. It helps make long term decisions easier.

Most open source projects are used by their owners, otherwise they are short lived. Not all of them need, or even should, be used by many.

Another option is to add a failing test.