A plea for better open source etiquette | Hacker News Reader

A plea for better open source etiquette

quickpeople.wordpress.com

103 pointsbenilov51 comments

I once submitted a pull request to add a feature to a popular OSS library. It got several "thumbs up", was actually useful, didn't change the API and had test coverage. I put a lot of time into making it nice and clean, in my opinion a perfect pull request. Two years later they closed it with a comment saying one of the more senior contributors added code that did what my code did (except 2 years later) so mine wasn't necessary anymore. They never merged my changes.

Objectively I can say what they did was cold but logical in the end, since it incorporated the change better into how they saw the next version of the library and they can trust the more senior contributor more. Subjectively it really hurt. It was one of my first contributions to open source and it definitely unmotivated me to do any others. It was in limbo for 2 years until they finally implemented it in another way, instead of just accepting the pull request for now until they could change it.

I don't hold a grudge against the people involved since I've used their code a lot and am thankful for their indirect help using their libraries. It just felt shitty.

Given that situation, I try and find the time to teach the original poster how to rewrite it the way I think it would be better implemented - with the understanding that if they don't want to, it's my responsibility to do so.

Then again, if I can't sell them successfully on why my way would be better ... maybe I should just have accepted their code.

This takes more time over the short term but in the long term lets me give out more commit bits, which I regard as a net win.

It is github, you had a fork, so anyone who wanted your feature in those 2 years could use your fork. And of course you got your feature and could easily merge upstream work as needed.

So what's the problem, aside from somebody you don't know not appreciating you? That person still gave you a great help (the rest of the project), and github prevented the difference of opinion from slowing you down more than a smidge.

That's very true. I appreciate your comment because it shows the situation in another light completely. You're quite right, and logically this is also what I should think, however it just, I don't know, feels bad. Irrationally, it feels shitty. We're still humans and I guess that influences us a lot.

Gulp. I'm guilty of this. An iOS component I shared became quite popular.

Now I don't even do iOS development anymore, Xcode is out of date, I haven't even used ARC. Whenever people poke me, saying that the issues and PRs are piling up, I tell them my situation and ask what they suggest I do. Surprisingly, my responses get no response.

Perhaps I should just add some of the past contributors to the commit access list.

I kind of wish that on Github, there was a default "untested" branch bit that defaulted to on.

On the back end, this would aggregate all the commits applied from a head, and allow the maintainer and contributors to know beforehand if their stuff applied cleanly.

Eventually, if the project is abandoned, this untested "uberpatch" would end up being the defacto main branch.

There are probably very many horrible problems with this idea...

Sounds like a security disaster, for one. I could submit a rootkit to every project on github.

A similar thing happened to me with youtube-dl. I handed the project over and gave commit access to a couple of contributors who are now doing an excellent job at keeping the program up to date.

Not long ago, this story was discussed here and makes a similar recommendation:

http://felixge.de/2013/03/11/the-pull-request-hack.html

Have you considered making it clear that it's not maintained anymore? Add [not maintained] to the repo description or something.

I'm an open-source maintainer who doesn't always answer issues and pull-requests right away. It sucks, I'm trying to get better. I can understand the frustration, but these sort of posts (or pleas or whatever you want to call them) always lack any sort of acknowledgement of the possibility that some maintainer's life may be different than yours.

> You could always have the courtesy to acknowledge the bug or PR I’ve submitted.

The thing is, you're actually implying more than you're saying. What you really mean is, "You could always have the courtesy to acknowledge the bug or PR I’ve submitted as soon as I submit it." You mention all the things you've done by the time you've submitted the ticket on Github, and I can appreciate all of that (I even wrote an entire article espousing your side [1]). The thing is, you did all that on your own time, on your own schedule. You're asking the maintainer of the open source project to help you finish solving your problem right when you submitted the ticket, i.e. on your schedule, with no acknowledgement for theirs.

To you, it might not seem like much to ask, for the maintainer to drop what they're doing to respond to your request. But some open source maintainers are very busy. They may get between 100 and 200 emails a day during the week. The Github notification from your submission is one of them. They may own a company, with employees to whom they are responsible. And they may manage many different projects, including several open-source projects. Even if it only takes 20 seconds to physically comment on your issue or pull request, it still requires a mental context switch, which they may not have time for that day, or even that week.

Furthermore, to be frank, it's often the sense of entitlement and lack of understanding that makes it unenjoyable to respond to requests. Granted, not all contributors feel entitled, but even having to deal with one entitled person is enough to destroy your motivation for the rest of the day. Imagine that you've spent years on some project, and fixed a hundred issues submitted by users, and helped many contributors get their pull requests merged. And now imagine the 101st ticket is someone who comes along and says, "All the time and hard work you've put into this project and provided for anyone to use free of charge is not enough; you're a disappointment because you don't respond fast enough." It's exhausting.

"If you don't have time to maintain the project, then mark the project as not actively maintained so we can move on," you say. But it doesn't quite work like that. It's not that the project isn't maintained. The maintainer may just be really busy this month. Or maybe they've been really busy for 6 months. They're still maintaining it, they just might not have time to look at things for a little while. Labeling the project as "unmaintained" would be short-changing all the people who are still actively using and developing and maintaining it.

"But my change is really small, just merge it in," you say. The problem is, you don't really have the context to make that claim with 100% certainty. You're not the one who has to deal with all the issue that may come rolling in due to some unintended and unforeseen consequence of your change. Also, if there are a hundreds or thousands or tens of thousands of people using the project without a problem, and you're the first person to report an issue, chances are your issue is not that urgent. That means, even for a simple patch, the maintainer has to weigh benefits of the patch with the potential that it breaks stuff for other users. The only "small patch" is one that changes a comment in the code. If you're changing an actual line of code, the maintainer rarely sees it as "small".

I don't type all this to make excuses. Like I said at the beginning, I understand the frustration. I'm not just a maintainer, I'm also a user of other open source projects, so I know. Uncertainty sucks. This is an area I'm trying to get better about myself as a maintainer. I even considered not submitting this comment, for fear of anyone misunderstanding or taking this the wrong way, and the inevitable "open source is a responsibility" responses. But I decided to submit it anyway, in case it helps anyone who truly wonders what the hell is going on, on the other side of that pull request.

[1] http://www.alfajango.com/blog/communicating-with-engineers-a...

I once got really pissed off when I submitted a patch to a project and got no response at all. I waited several days, but when I saw that the maintainers were responding to new threads on the mailing list -- not just to existing threads -- I got upset and wrote something intemperate.

I'm not proud of that, and have no intention of doing it again, but I did and do think it's rude not to reply at all. "Thanks for the patch; don't know when I'll have time to look at it" is enough. I did, after all, go to the trouble to track down the bug and devise and test a fix.

I have gotten upset about a submitted patch going unmerged, also, but only after a couple of years had passed. I agree, pressing maintainers to merge one's patches promptly reflects a certain self-centeredness.

> ...but I did and do think it's rude not to reply at all. "Thanks for the patch; don't know when I'll have time to look at it" is enough.

You're probably right. All I can say is, when you get 100-200 emails a day, every day (it doesn't stop), it's hard. That's not an excuse nor a justification. it's just a statement, an explanation at best.

Also understand that your expectation of a maintainer's response, however small or trivial, is at direct odds with the time they spend working at their day job, or spending time with their family, or relaxing. That's not to say open source maintainers don't enjoy building and maintaining open source projects. Most do (including me). It's just the recognition that maintaining open source projects comes at the expense of other things which they also enjoy.

In the same way that I believe you're justified in thinking a maintainer's non-response is rude, I believe a maintainer would be justified in thinking your expectation of them is also rude.

> ... when you get 100-200 emails a day, every day (it doesn't stop), it's hard

Fair enough. In that kind of situation, the only hope may be to use an autoresponder with a canned message. (This would at least assure senders their messages were received.) And try to recruit some co-maintainers :-)

Yep, ran into the programmer's-autoresponder for the first time from the dev of the AlarmDroid app for Android. It's pretty effective.

>responding to new threads on the mailing list -- not just to existing threads

Not all threads are the same, some are very easy to respond, and some require a lot of thinking.

The hardest pull requests are those which are useful in some way, but not really ready to be merged, and maintainer needs to do quite a lot of work to either explain what is wrong with pr or to rework it.

saying "Thanks for the patch; don't know when I'll have time to look at it" as a default response and leaving it for a month isn't very useful, and if it is a "default response", one can assume he got it just by sending pr and not getting other response.

I see people in this discussion getting wrapped up about manners and expectations. What I'd like to contribute is this:

I think in a position that attracts a pile of daily email, you need to be able to triage what you read, saving some ( hopefully few mails ) for later detailed reply, ignoring junk and hammering out a pile of short acknowledgements as you go. It doesn't take much more time to hit reply with "Thanks, go it, will process as time allows" or similar. If you don't do this, you're treating it as junk mail in my opinion and robbing the sender of any acknowledgement. If you've _got_ to ignore valid mails in this fashion, it points to some other workload related issue.

If the OP would consider becoming a maintainer of a project they contribute to, and then follow their own advice, they do have some warrant to their complaints, otherwise not so much, for the reasons you state.

I got a substantial pull request to an open source project of mine [1] that I don't have much time for, and followed the "Pull Request Hack" [2] and made the committer a maintainer. My GitHub notifications for that project now follows this pattern: "Random user: Hi, please merge my changes", "Maintainer: Thanks for your contribution, I made some changes and merge it in!". That's pretty fulfilling.

1: https://github.com/jacobrask/node-upnp-device 2: http://felixge.de/2013/03/11/the-pull-request-hack.html (although this was before I read the article)

I've taken over the maintenance for a project a few months ago and have tried to stick as closely as I can to what I wrote about.

I've also used the pull request hack, it's a really good idea!

> I even considered not submitting this comment, for fear of anyone misunderstanding or taking this the wrong way, and the inevitable "open source is a responsibility" responses.

I'm glad that you did, thank you for taking the time to respond.

> The thing is, you're actually implying more than you're saying. What you really mean is, "You could always have the courtesy to acknowledge the bug or PR I’ve submitted as soon as I submit it."

While I've definitely been guilty of impatience in the past, now I try to measure the response against some kind of "OSS time", which is a lot more forgiving. I appreciate that people are likely to be busy, or away with their kids in Hawaii for the past two weeks.

Having said that...

> The maintainer may just be really busy this month. Or maybe they've been really busy for 6 months.

I think one month is a bit long to have to wait for a response. 6 months: most certainly too long. In those cases, the "pull request hack" [1] may be the way forward.

[1] http://felixge.de/2013/03/11/the-pull-request-hack.html

> I think one month is a bit long to have to wait for a response.

You're certainly entitled to that opinion, but the amount of time that is "acceptable" is completely subjective and relative. Holding someone else to your own arbitrary standards of acceptability is exactly what I'm referring to when I say these sort of complaints usually ignore the possibility that someone else's life is different than one's own.

I can see how a month would seem like a long time, it used to seem like a long time for me too. But for someone running a company, someone with a crazy family life, someone maintaining several projects, someone getting married or divorced or having kids, someone buying a house or selling a house or moving, someone in school, someone having financial troubles, etc., etc.; a month can be a blink of an eye. You, of course, are welcome to your opinion. I try to avoid holding people for whom I know nothing about to my own arbitrary standards, and try to withhold indignation if they don't live up to them. I admit it takes effort; I often find myself doing exactly that. I just have to remind myself that I can't really know them to the extent that I know myself, and thus it's not always fair to expect that their situation lends itself to meeting my standards.

EDIT: All that being said, I think the pull request hack could be a potential solution. It does however bring its own potential problems. You're basically putting your reputation in someone else's hands, whom you don't know. Of course that may be preferable to what you're doing to your reputation by taking a long time to respond to requests. I'm certainly considering it for a couple projects.

> Holding someone else to your own arbitrary standards of acceptability is exactly what I'm referring to when I say these sort of complaints usually ignore the possibility that someone else's life is different than one's own.

I agree with the spirit with what you're saying, this is indeed all opinion.

I see it like this; if you're walking along and say "hi" to your neighbour, he doesn't have to say "hi" back, but it's nice, 'sall :)

I agree. I certainly don't feel like we're arguing, just adding more pieces to both sides of the puzzle.

I guess what I'm saying is, if the neighbor doesn't say "hi" back, it might be for reasons you haven't considered, and it might not be as simple as asking them to just say "hi" back.

Context and scale are extremely relevant here. I can say "hi" to every stranger I pass while hiking on a remote forest trail. However, I cannot say "hi" to everyone I pass walking down the street in Manhattan. Snubbing the passerby in the forest would feel rude. Ignoring the passerby in the city is normal.

I thought the whole point of Git/hub is that branching and merging is so easy/powerful that you never get blocked waiting on uptream to integrate your fix. You just fork (on click), fix, PR, and merge later. Kids these days...

And then maintain your own fork for the rest of your application's lifecycle. Not the brightest idea.

> Or maybe they've been really busy for 6 months. They're still maintaining it

If the project has pending issues and patches for six months, it is not being maintained.

If it is something that has a large user base, I think the owner has some degree of responsibility over the community. Either add other people to project or mark it as unmaintained, allowing a fork to take over. All too often you'll find a zombie project where the author abandons it for months, yet doesn't want to let it go; if he is a well known dev people will still flock to his project because he says it's "still maintained, I'm just busy", making it harder for a substitute fork to take over. Everyone loses.

The LibreOffice guys are particularly good about code reviews and accepting patches. In fact, they use gerrit (http://gerrit.libreoffice.org), and I'd have to say that one piece of infrastructure has increased contributor patches exponentially.

There is only one answer to this:

I would be very happy to review and merge your pull request. I charge by day and my daily fee is 600 euro. Bank details are bellow, once payment is cleared we may proceed :-)

Now seriously: Every minute I spend on my OS project I have to cut from my sleep or from time with my family. I would love to review patches, have a chat and perhaps get a free beer, but it is simply not possible.

For project maintainers there is simple way to avoid this overload. You need to 'manage your community growth'. If it grows too fast you will be flooded with bug reports, pull requests and emails.

For my project I have not provided build system and binary builds for a long time. Users were forced to use IDE and study the code. Also I did not provided any documentation, just a code examples. Key is to attract people with coding skills, who can actually grog code.

Also be careful how you advertise your project. You should actually target co-developers (with commit access) instead of users. For example if your project is written in Coffeecript, you should avoid using word 'javascript' on front page and in readme.

Sure it hurts number of users in short term. On long run it increased number of power users who do bug triage and answer support questions. The key is to grow number of co-developers together with number of users.

An interesting pattern I've come across lately is a project where contributions are almost universally either rejected or rewritten (largely superficially) by the original author of the project. I think I dislike this far more than a lack of response, though I've experienced that as well.

I've done this. Had a pull request from a contributor that added a feature, but in return changed the API of my library almost completely, didn't account for many, many edge cases and had a couple of bugs. When I was done I had rewritten it completely, but I still attributed the change to the original contributor. In the end, I'm pretty sure I invested more time in it than he did, but fair is fair imo.

i've submitted some non-trivial PRs with tests to large projects that are still waiting for any form of acknowledgement after several months while other PRs and new commits are being closed around them. it's definitely annoying. maybe it's a github hellban :)

As a maintainer of a project with almost 2000 stars on github, I sway back and forth between being allowing ("Just submit code to get what you want done. We can fix it once its in the repository") and a stickler for details ("I don't want your change until you give me tests.")

I really wish I could just give everyone who submits patches commit access and let them at the repository. It would save me time. It would save you time. It would make my project better. And I don't write opensource software because I enjoy being a policeman. I hate it. I hate saying no to real work that solves real problems. Unfortunately, the majority of pull requests are simply bad.

- Many do not understand the project's conventions (eg, if my project is written in coffeescript, so your code needs to be in coffeescript too). Example: https://github.com/josephg/ShareJS/pull/36/files . After I insisted on the code being ported to coffeescript, several users whinged on the project's mailing list about my language choice.

- Most pull requests don't have tests. Submitters usually don't even run the unit tests before submitting, and their pull requests often break the tests we do have. I understand that you don't write tests in your application, but the rules are different in an infrastructure project that many people rely on.

- People often have extra modifications in their PR that have nothing to do with the patch. For example, this pull request has good parts near the top and also makes my code uglier riiiight down the bottom in the name of 'optimization'. Quotes because optimization was never run, and the changes didn't actually improve performance. https://github.com/josephg/Chipmunk-js/pull/15/files

- Some bug reports exist only to waste my time and complain about my programming language choices. This is what I was doing instead of triaging your bug. I'm sorry, ok? https://github.com/josephg/Chipmunk-js/issues/11

I usually err on the side of allowing changes and fixing stuff later, but my projects have suffered for this several times. I've had maintainers accept pull requests that break the unit tests (and leave them broken for weeks). I've had otherwise normal code suddenly sprout extra levels of indentation. I've had mountains of bugs appear, filed against a feature I didn't write, don't understand and I never use, who's author has disappeared. I've been burned enough that I can totally understand maintainers who ignore patches and bug reports.

I still love everyone who cares about my projects enough to submit a bug report or takes the time to make a pull request. I need contributors to make good software, but it breaks my heart when nice people submit slightly bad code, and I need to either whinge at you or stop working on my own pet feature to clean up your mess. I'm sorry to everyone who's patches gets ignored, but sometimes I get tired too.

In short, its fun to complain about The Man because your precious donation of code is being ignored. But its just as thankless running a project, only we shoulder way more responsibility and burn way more time doing it. If you want me to look at more of your bug reports, help triage my other pending bugs and pull requests. If you want me to stay excited about the project, email me to say how much you like it, and tell me about the cool things you're doing with my code. If you want commit access, ask for it. Finally, if you think you can do a better job running a project, use the fork button and do something about it.

I definitely didn't want to imply that "you should merge any ol' crap".

I was commenting more on how maintainers communicate (or don't communicate) their feedback. I see no problem with saying "please add tests", or "don't break the existing tests". Some of that can be managed automatically with the likes of Travis, other stuff like "I only accept code that's coffeescript" can be mentioned in the CONTRIBUTING file, and your reply to the PR can just point to the rules. I don't have a problem with any of those cases; it's stony silence that gets me.

Definitely be a stickler for details, I'm infinitely happier seeing a PR unmerged and closed with a solid short explanation, even if it's "does not fit my style", than waiting indefinitely for a reply.

RE those pull requests: some people like hating on coffeescript. Chipmunk-js/15 is just a terrible patch...

...What should I do if I want to fix an apostrophe in your readme? GitHub is making it difficult for me to do a #L link to your file but:

- It is slower than the C version (duh, its in javascript). Specifically, physics simulations using chipmunk-js runs about 3 times slower than the C equivalent.

should be

- It is slower than the C version (duh, it's in javascript). Specifically, physics simulations using chipmunk-js runs about 3 times slower than the C equivalent.

More projects should look at and adopt the Web Hypertext Application Technology Working Group (WHATWG) HTML Living Standard page (http://www.whatwg.org/specs/web-apps/current-work/multipage/...).

You can see status annotations in the left margins that allow you to go to extended/extra information on each section. If you have comments/questions on a section, you can use the widget at the bottom right (it says "Click the location of the error to select it, then type your message here:") to submit a review comment.

I feel like a lot of these requests, especially in the "For a PR" section are things that only more seasoned developers have an appreciation for. Since OSS runs the gamut from bad-ass-mofos to beginners, I feel like you're going to get under a 50th percentile in most of these areas.

I agree that things need work, but sometimes it's hard to get to everything, especially if you're doing it for free in spare time.

Some of it comes from the fact that a lot of "bad-ass-mofos" are beginners.

I know it's really not fair to group together people (not everyone's the same after all), but a lot of the etiquette issues seem to stem from a common lack of manners by and large.

Also of note: Times have changed. Once upon a time, most hackers tucked their shirts into their pants. Now some have stretched earlobes.

Stretched earlobes and common courtesy are not mutually exclusive in the slightest.

It's a metaphor for the changing times, not common courtesy.

I think I tend to be rather obsessive about answering, replying and the occasional PR I tend to be really excited about. However I almost always want to tweak the PRs and I don't always have time. I have been guilty of letting some go for a few months, but I did acknowledge and discuss them right away.

One of the easiest etiquette techniques projects can adopt is to only have the person who opened a ticket close it, in both cases where a fix was applied or it was decided not to fix.

This lets the originator of the ticket verify that the issue has been resolved or that there is no issue in the first place.

Edit: clarification

This standard practice at every sane organization and bug tracking tool. Which is not many of them, sadly.

Everyone I've ever tried to send a PR to had been very responsive. The rauth guys (litl) are great. I added some AppEngine docs for Line Profiler and I think they got pulled the next day.

More important etiquette: don't make such demands and complaints on maintainers. Incorporating other people's code into a project can be tedious, risky and unrewarding.

We don't want bug fixes with your whining

I just want bug fixes. He wants his work acknowledged. Seems pretty reasonable!

It's not the job of open source maintainer to acknowledge every nitpicky little turd (like the mentioned documentation typos) that some guy found.

Actually, that's what the job of a "maintainer" is. Now, no one has to be a maintainer if they don't want to.

Would you prefer I left your typos in place?

Reply on news.ycombinator.com