Hacker News Reader

Comment by Klathmon | Hacker News Reader

I have a question for any OSS maintainers:

How should I ask for help/bugfixes/solutions? How can I get across that an issue is a "showstopper" for us without demanding anything? How can I offer solutions or fixes or changes up without contributing to the "burnout" that i've seen many many times from many people that I respect and enjoy the work of.

Recently I was inadvertently one of those nameless-faceless demanders, and I had no idea that I was coming across like that until it was pointed out to me.

I want to voice my opinions, my needs, my use cases without coming across as demanding or winy. And making a PR out of left field generally causes more issues than it solves since it was made without direction or input from the maintainer.

View on HN

IMHO:

1) Just ask whatever you want, no limits, but without expecting it to be done. There is just the possibility that it will be done.

2) Provide as many details as possible so that the maintainer does not have to context-switch to understand what's going on.

Point "2" is very important. Example: pull request subject is "fix hash table crash". Only change is a one liner like:

    - if (next) {
    + if (next && ht->used != 0) {

No mention about what are the states causing the crash. Now, as a maintainer you HAVE to understand what's going on, you can't blindly merge a commit otherwise you'll likely merge many things that are harmful instead of fixes.

So now good luck with stopping with what you were doing and understanding what happens if ht->used is not 0 in that case, and the corner case that triggered it.

Instead in the original PR description, the contributor shold have written: when the hash table is reset, if there is a running iterator, next will be NULL because bla bla bla. Testing for empty hash table instead bla bla bla.

Now your effort is 30 seconds... Understad, merge, say thank you.

Also if possible include a unit test in the PR, maybe even in a separate commit.

For example, let's say I'm a project maintainer and I get a PR with two commits. The first commit just adds a test case, and Travis has marked the build for that commit as failed. The second commit includes a fix for that case and Travis shows that the tests pass when run on that commit. That's the sort of PR I can confidently merge without even having to leave GitHub's web UI.

Start with a small praise and how the project had currently helped you. Even just a "Thank you for this awesome tool!" goes a long way.

Do a bit of story telling about why you want this or that. Try to make a good case of it.

Post as most as possible, code, backtrace, steps to reproduce, what did you tried, etc. In a structured way.

Assume you may be wrong. Use words like "Maybe", "We probably should", "I may be misguided, but", etc.

Format it correctly, check for spelling and errors.

Finally, reply back when asked for stuff.

It's not that hard, but most people aren't doing it.

Hopefully this Issue/PR [1] I opened today to clarify documentation would make good live example of this :-)

[1] https://github.com/BurntSushi/ripgrep/issues/284

This is just a general front line support problem. A poor problem description or incomplete problem description is irritating and gets to people. The other one is the people that only show you step #4 of a procedure they are using and keep trying to point to that as the root cause while it was really step #2. An issue report should show from damn near install to the observed problem, or thorough enough logs/config/stacktrace to give people on the receiving side enough information on how you got here. I call this the A-B-C-D problem, where they only keep telling you about something breaking in C but nothing about A, B or D that feeds in.

The assume you may be wrong attitude to take in problem description is definitely something I have seen well received as a reporter and a recipient. Issues that are submitted with a tone of finality and then it turns into a problem resolved by configuration/FAQ/documentation can be frustrating, because in the triage you have to ignore such language and verify anyway.

The unassertive language also clues the reader of potential knowledge gaps in the reporter. Inevitably just by construction of the report

Also this was something that was mentioned in postgres response after I believe Uber transitioned from the technology to MySQL recently- if you are doing something massive/slightly insane it helps build a strategy. A communication issue from VPS host to VPS host for MySQL will require a different diagnostic strategy than microcontroller to microcontroller MySQL connection over an TCP/IP on I2C bus duct taped to the bottom of a Honda Civic.

Other than the bug reproduction instructions it seems like you could train a piece of code to convert requests to a format like this using machine learning. It could save someone from a lot of stress! (I agree with your point but even solving it this way would provide benefits).

> Start with a small praise and how the project had currently helped you. Even just a "Thank you for this awesome tool!" goes a long way.

This might be good advice in general, I'm not sure, but I mostly see this as just noise and it won't make me more likely to respond quickly or take any action. In terms of politeness, I think the more relevant quality is how entitled you come off as. If you come in saying, "This needs to change because of <downstream product requirement>", it makes me think you probably are thinking of the change in terms of how it helps you. If you come in saying, "This is the problem I'm having, this is the workaround I came up with, but this doesn't seem like the right behaviour because <x>", I'm more likely to figure that you actually took a holistic view and are thinking about how this change would affect all downstream users.

I'm not a maintainer.

That said, I've never had a problem with non demanding, humble, zero pressure questions.

Why do you need to mention that something is a showstopper? This may sound harsh, but: at the end of the day, you have to be responsible for what you produce. That means if there is a showstopper in their project blocking you from getting something done, you, and not them, are responsible for dealing with it. They volunteer to maintain the project for everyone, not fix your problems on your timeline.

The "example" I had in my head when writing that one where I found a pretty nasty bug in a relatively small library I was using.

I opened an issue, but struggled on how to get across the feeling of "If this isn't fixed i'll need to do it myself", but without the demanding feel.

I'm completely okay with a "can't get to it now" and i'll take over and fix the problem in the library myself for myself (making a PR if it makes sense to), or completely replace it with my own code or another library. And I would never fault the maintainer for not having time, or just flat out not wanting to fix it for me.

But having written that out, I see what you are trying to say. There's no need to point out my timelines, or ask for an ETA or anything like that. At the end of the day I'm responsable for my code, so I'd be better off just making the issue about the actual issue, and set a deadline (internally in my team or to myself, not publicly) that if it's not fixed by that time I do it myself.

In your example the answer seems clear to me, communicate that you have a deadline, but are willing to fix this if they are busy and ask them if they have any thoughts on how they would like the issue to be resolved.

Exactly. I am very comfortable saying "please send a pull request" in response to the request for a feature, or the report of a bug. I try to be overtly encouraging, suggesting that when people suggest ideas, they dive in and try to build it.

The best way to scale a project and community is not to try to do everything yourself, and instead encourage other people and empower them to act. They may need assistance in the beginning, but the benefit will pay off in the long term: "If you give a man a fish, you feed him for a day. If you teach a man to fish, you feed him for a lifetime" (attribution unknown)

This does require giving up some control. Properly empowering people to contribute means that you need to, to varying gradual extents, respect their judgment and not try to veto or assert too much control. No person will work on any one project forever, and so a gradual and seamless transition of project leadership from one person to another requires a gradual trust in the other's judgment; trust in judgment necessitates room to make mistakes.

If you need something from a project or organization that you are not paying, then do not engage with the expectation that they'll do work for you. Instead, engage as a collaborator by offering to bring something to the table. Point out the bug, offer to fix it, and suggest a possible solution. Or if you just want to point out the bug, that's fine, but don't carry an expectation that someone will volunteer to fix it for you.

First and foremost, be nice. Secondly, you should assume that anything you "need" will not be built by anyone but you. If you end up with a "showstopper" in OSS, it is time for helpful contributions. Either that or you should find a different solution. A helpful contribution might including opening a civil dialogue about a feature. "Is this a feature that the project could consider within scope? How could I go about adding that feature?" Ask for guidance; don't demand solutions.

How should I ask for help/bugfixes/solutions? How can I get across that an issue is a "showstopper" for us without demanding anything?

"Can I hire you to fix this? If you're not available, can you suggest someone else I could hire?"

It doesn't even matter if I want to get paid (and for small things I'll often encourage people to make a donation to the FreeBSD Foundation instead); the fact that you're offering to pay for work communicates "this matters to us" far more clearly than "OMG THIS IS SO BROKEN WHY CAN'T YOU FIX IT ALREADY???".

Invest some more of your time into your request. Like said before about context. The less the maintainer has to switch into the context of the problem and try to understand what is the underlying problem (which is often the case) the better.

Always read into the projects contribution guidelines (if any) and read into the project development structure (tests/CI, style guidelines, architecture, bug report templates). Most of the times there are ways to take load of the maintainers. Take example from other contributions and similar features in the project to 'feel' the projects architecture/design/style and always look at the bigger picture of your proposed change/request.

Don't make it about fixing your specific problem but about improving the project in general for everyone.

And like said before, you can ask for anything, but should not take an expecting/demanding attitude. After all these people are already saving you tons of time and money.

IMO, if you end up in that situation, you need to invest more effort into figuring out a good solution from the library perspective & maybe even be willing to spend the time to implement it - that is the only way you can effect positive change in a more guaranteed fashion towards something that will solve your pain point.

Problem is, if you don't come up with a solution, there's no guarantee that the maintainer(s) will be willing to act on it (depending on severity, risk of impact to other users if a change is made with [insert issue], priorities, etc.). If you invest effort towards figuring out a solution/figuring out what is wrong, it helps maintainers dramatically. If it is a persistent pain point, it may be even worthwhile to have a developer devote some time to becoming a maintainer of the project itself, so it derisks your business.

> How should I ask for help/bugfixes/solutions? How can I get across that an issue is a "showstopper" for us without demanding anything?

While I know that from experience that these situations can be frustrating and even costly, why should your showstopper put an onus on anybody but you in absence of a support agreement?

I think here you can certainly ask and explain your situation. But if the answer is "no, I can't right now", your response needs to be to find someone with the knowledge, time and willingness to make the change on a fork of the original repo/source. This may require a contract or other arrangement.

It may or may not ever get upstreamed - because upstream has to consider whether a given approach to a fix is in line with what they want for the direction of the project. Regardless, though, it ensures you get the fix that is a critical showstopper for you.

Don't demand, just explain. Stay positive, don't whine or despair, just explain.

File as _good a bug report as you can_, which means taking _extra time_ on your side to do so. The ultimate is a bug report with a failing test case and/or demonstration app.

By the time you're there, you're often more than half a way to actually fixing the bug and sending a PR/patch, which is of course great too, but not neccesary to be a good bug reporter.

But do as much work as you can when filing the bug to save as much time as you can from the responder. Clearly describe the context and problem, what happened that you think was wrong, what you expected to happen as 'right'. And actual code demonstration in the form of failing test or demo app is _amazing_.

I'm not a maintainer, but if it's a showstopper, then it seems like you should just get a developer to write a patch no? You could probably ask the maintainer whether they can help do this, but if not, just ask for (potentially paid) assistance so that they can help your developer get up to speed on how to fix it.

In the worst case you would just have a separate fork until the patch is accepted upstream, assuming that happens at some point.

I always thought the norm, when dealing with an open-source maintainer, is that you fix the problem and offer a patch to them. I generally won't just E-mail a maintainer or file an issue, and ask them to fix a bug in their own software for me.

Also, there's no such thing as a "show-stopper" in OSS. The show has already happened. The software is already released.

How are things different with non-OSS software?

If you use a proprietary software application and there is a "showstopper", what happens?

I get my boss to call the regional sales manager for our account, and say we're paying lots of money and we're gonna find a way to stop unless they can fix or provide a workaround for the bug. If it's truly a "showstopper".

Well at that point it's a 2-way street. I'm going to ask for a solution or direction as I'm paying for it.

However with OSS I'm not. And while i'm more than fine with a "wontfix" or something similar (at the end of the day if the software won't solve my problems, that's okay, I'm not forced to use it, you aren't being forced to maintain it), I'd like to know how I can at least ask without contributing to the problem.

And even if I wanted to "pay" with contributions, they aren't free for the maintainer either. I know all too well how a well intentioned fix or change can end up causing more work and annoyance than an issue asking would have.

Why not change the relationship?

Find a contributor - on the team or not - working in that area and ask about their rates and what it would take to hire them. Some will not be interested but some will be.

At that point, it's a patch but created by someone active in the project. The worst case is that you can apply it yourself. Not great but immediate problem solved.

Long term, when you go back to the core team, you have a patch that has been tested and used, built by someone in their community, and you're not making a demand but helping address a gap (real or use case specific).

(I've worked on and managed OSS projects for 10+ years and this works pretty consistently. It requires a little more work up front but you end up with a better relationship with the maintainers and a growing network of people who you can contact for specific issues.)

>Well at that point it's a 2-way street. I'm going to ask for a solution or direction as I'm paying for it.

>However with OSS I'm not.

Open source software is not the opposite of free (as in money) software. Saying this not just for you (maybe you knew it and used the term loosely) but for others too since I often see this wrong use of terms, sometimes even among people who one might think should have known of it.

There can be (and is) for-pay open source, free open source, for-pay proprietary and free proprietary software - all four possibilities. The two dimensions are orthogonal, sort of.

The fact that one or two out of the four kinds may predominate, does not change the above points.

May seem pedantic, I know, but isn't, really, IMO, and I think is worth clearing up this misconception.

Edit: typos.

Yes, that's a good point. Red Hat Enterprise Linux is open source software, for example, but many companies still pay for RedHat's support services, because the task of doing for yourself what they do for you can be complicated, especially where it comes to understanding, ingesting, and building security patches and things like that.

You tell the people who sold you non fuctional software to fix the problem.

That relationship does not exist with OSS projects.

microsoft/oracle aren't gonna jump whenever some random customer says... I've had good to great experiences with msft support, but our 50 licenses or whatever just don't matter.

Create an issue along the lines of what many people have suggested already. At the end ask if the maintainer would be open to a PR for the issue. If they are go write that PR, if it truly is a "showstopper" it should be a no-brainer to spend the time on that PR.

>How can I get across that an issue is a "showstopper" for us ... ?

If it's costing you money and you're an IT shop, I'd hope you could task a dev to spend an hour or two to fix the issue and provide a patch.

The solution is to get more personally involved. They don't owe you anything.

While that's true, even contributions can contribute to the burnout, especially when they are made without any input from the maintainers.

The classic "massive PR that changes how something fundamentally works" comes to mind. And while I'd hope i'm not going to do something quite that big, throwing a bunch of code at them and saying "put this in?" feels much worse than asking. Not to mention that it will end up being a waste of my own time as well.

Reply on news.ycombinator.com