Love Your Maintainers

♪♪♪ Hello. Welcome to Love Your Maintainers. First of all, let me introduce my company, that's Platformatic, which is the best way to build your Node API and build your Node backend. We provide a comprehensive automated solution for API, GraphQL, and integrated servers and services. Check it out.

Now, the secret is in the manners. It's how you ask people how to do some stuff. Let me prove you how. First of all, I would like to introduce myself. I am Paolo. I'm a Node TSC member and also principal engineer at Platformatic. You can find all my handles down there, especially my website, which I just redesigned. So I encourage you to take a look and give me feedback, please. Okay. Now, let's move on.

What do you expect, pretend, from open source? What is the right verb to use? First of all, let's clarify what is actually open source. Open source is a decentralized software development model that encourages open collaboration and is driven, and this is the key here, by the passion of the people. Now, it is working and it is definitely working. Open source has proven to be really effective when it comes to improve software quality, services, and on some extent, the life of people.

It all started in the seventies, in the free software movement that challenged the traditional for-profit-based development as usual. The problem is that in English, as you might imagine, free means too much. It both means free as in not paid and free as in freedom. It's ambiguous. Not paid was the most understood meaning of the word. Therefore, it was changed to open source, which is a branch of the free software movement, so we get a clear understanding of what it means. Open source is a software that can be used for commercial purposes without retaining, sorry, giving up the freedom. The freedom is retained. Now, why would somebody want to go open source? Because, and allow me the quote here, you can get the best of the best of the best. You can access a developer base which is not even remotely physically close to you, and you can access different culture, backgrounds, and capability, which means different point of views. In every aspect in the human life, this has proven to be a increase in the quality.

Also, you have low maintenance costs because open source software is maintained by other people for you, so you don't need an office, and if you embrace open source, you just need a version control server. Now, you don't need an office, right? This is presumable, so something, right? Does it ring a bell? Well, open source is similar to remote working, but it's not. Beware of this, and this is the key of the rest of this entire talk. The huge difference is that people in open source are driven by passion, not by money, and moreover, you are not their boss. Remember that. You are not their boss, so you cannot demand anything. You can ask, but you cannot demand. You cannot command. You cannot do any orders, but in general, everybody is nice if people are kind.

Now, remember, people in open source are driven by passion. Maintainers love, simply love that you use their software. Otherwise, they would never have open sourced it, but we need to give everybody respect. Maintainers don't owe you anything. They are giving their time, their free time, their personal time, their hobby time for free for the passion, but you're not paying them unless you sponsor them, but that's a different topic. Remember that action have consequences, like usual. If you pretend fixes, if you pretend features, or if you just demand attention in the wrong way, you will push people away, like it always happen in any other social aspect in the world. It's not just open source. This applies to everything. This is a general life lesson, if you allow me to give you a lesson.

Also, what you want to do, you want to avoid burnouts. You don't want people to simply burn out. Remember that on the other side of the screen, there are other people. There are people which, like you, have sentiment, have need, and have real-time work. They have real life, they have hobbies, they have family, they have children to take care of, and so forth. Even a single small act of rudeness can burn people out. Don't forget it. What you think might be just a small act of rudeness might be the N plus one that maintainer has seen nowadays, and people will burn out, and eventually will give up on the software. As you can see in the screenshot, I take a snapshot of the GitHub page of the LWJS project, which was managed by James Sumner, which received a nasty, nasty, nasty, and honestly, completely pointless message by a person which was able to put a huge amount of curse words and offenses and rudeness in just six lines of text. James burned out and said, you know what, I'm done. Nobody's paying for it, so therefore I'm retiring the project.

The project is decommissioned, and now nobody can actually benefit from my work on that. You can still fork it, obviously, because James was a good guy, could have just removed this project whatsoever, but he was a good guy. He chose to just say, the project is now archived. If you want to fork it, it's your own now. I'm not going to give you my time anymore. So that useless rudeness got to nowhere, right? Please avoid that. Be kind to people. Be very kind to people. The human side is what I care most about today. We have to be kind with people which we relate to in open source and in general. It never is a problem, actually.

Now, let's say we are kind, we are eventually able to behave in the right way. How do you ask for help in the open source project? Well, first of all, and it will surprise you, you have to search. Start with a very detailed search. This is my list of priority order when I actually have to search for stuff, because, of course, I use open source software, which I haven't written, so I have to search eventually for issues, right? Sorry, to solve issues. And in this case, this is my to-do list when I have to make a search.

First, I start with the issues. Let's see if I have a problem that somebody has already encountered. The easier is to reproduce this problem, the higher is the chance that somebody already reported it and also that is already fixed, but that's another topic. Now, if I don't find anything in the issues, I switch to the PRs. Maybe somebody noticed that instead of filing an issue directly, proposed a solution for it. So PRs are next. Then there is the code. Try to lean in the code base if possible and search if there is already some lead on how to fix your problem. Maybe you're just using the software in the wrong way. Late documentation, that's the last one. Maybe there is a very nifty page in the documentation that has this non-workaround for the issue or specifically it says that this problem will not be covered because it might be. Of course, this list is after you already read the documentation for how to use the software because I'm assuming that you already did it. So in other words, please don't get somebody reply to you without reading the fucking manual, okay? But anyway, that is my list.

Now, I also had a side note to make. If you have a really trivial problem to reproduce and nobody has ever reported it and nobody has inserted a PR for that, dude, you're using it wrong over that. I'm telling you because it happened to me many times. I couldn't find any solution. I couldn't explain why nobody has ever encountered my stupid problem and then realized that the stupid in this entire portrait was just myself. So you know, double-check anyway. Another very important thing. We live in a distributed world. We live in a world where we are distributed across the globe, where people coming from different cultures, so with different expectation and knowledge and expertise. I'm not just talking about two-pronged source. I'm talking in general. So never worry about over-communicating.

Put as many details as you want, as many. I will come back on this later. And don't be afraid of annoying people with over-communication. The more details, important details you can give, the better it is, because think about this, maintainer have their own life, so they might not have the time to request additional information and they will probably, therefore will not process your report if they are lacking crucial information. So do not be afraid to over-communicate. And forget, and this is will shock you, working on open source and reporting issues and investigating issues is like a journalist. Do you remember the WH rules? Who, where, what, when, why, and how? That's the same. We start with who and where. Usually if you're reporting an issue with a software, who is the software itself, right? But it's not always the case because it just might be one part of the software. So try to be explicit if you can. Of course, don't provide useless information, but you can.

Then, and this is the most important, what and when. Explain what happened, what did not happen, and what we're actually expecting for the software to do. And when it happened, what we are doing when that happened, try to provide the more comprehensive context you can possibly can. Then there is the how. And remember, this will return. What is the smallest way to reproduce the problem? We don't, I mean, you have an amazing application, you're maybe using just a package. I don't think that the authentication of your application matters for this package if the package is not the authentication package. So we don't care. Try to narrow down the problem. This will return in a bit.

Now, very careful reader might say, dude, you forgot to mention the why in the list of the five W's, right? I have not. Why something happens is a controversial because if you know the why, as a reporter, it means that you already know how to fix the problem. In that case, please provide a PR, or at least provide a detailed explanation or an issue to how to eventually solve the solution. Maybe you don't have the expertise to touch the codebase, but you understand what's going on. But usually you don't have the why, except in some cases. So I haven't actually forgotten that. It's important, but it's not part of the summary for this. Sorry, I skipped a slide. Now, I was talking about overcommunicating, but make sure you don't float maintainers with useless information.

You don't have to worry to overcommunicate, but you can't, of course, exceed. As they say in Latin, in metastat virtus, so the virtue stays in the middle. You can't pass tons of output or maybe gigabyte of output in an issue because nobody's gonna read it. Also, reports with a lot of information will likely distract maintainers, which are someone who will lose interest and don't even look at the issue, even if they're willing to help.

Moreover, which is the direct consequence of all of this, it is for your own good. The more superfluous information you give, the less the chance that your issue is gonna be fixed, because if you lose the maintainer attention, you're done. If the maintainer sees a lot of output with no interesting information, it will not fix your issue and you will be left alone.

Try to find a good compromise between what needs to be communicated and all you can communicate. Then we get to the core of the idea. The very best way to ask for an issue, to ask for a report to a fix or anything like that, is to create what are called reproducible repositories. So if you get a software, you are using it, you can create a repository just for that issue that only contains the minimum details needed to reproduce the issue. You of course want to remove all the sensitive information or max or obfuscate them, and please provide a public repository. So triagers or maintainers can just clone your repository, start the repository, look at the issue, isolate it and fix it. That's by far the best way to get a fix, okay? I'm not gonna tell you how to create this thing, you can search it online, but the core is that minimal, isolated, public, no sensitive information. If you keep that, you're good.

Let's move on. The last advice I want to give you is follow up. It's very obnoxious if you file an issue and you forget about it, and then eventually you come back in a month saying, oh dude, is that fixed? It will probably will not. If the maintainer immediately ask for more information, you never replied, maintainer is stuck. We don't have the magic ball, we can't really read the future, so you have to give all the information we are asking you in order to fix the issue.

Also, your only occasion to be heard. If the issue basically involves a feature that is missing or an improvement that can be made, and if you want to chime in and give your own opinion, this is the last moment because once the issue is fixed, the new feature is merged, the new PR is made, you don't really have a voice anymore. Yet, of course, you can report a new issue, but maintainer might never change that because it actually works. And moreover, there is also the semantic version in problem involved and so forth.

So my advice is set up notification that you read. For instance, I don't use GitHub notification, I prefer to receive emails by GitHub. Whatever suits the most for you, make sure you stay up to date to the trend and you follow the discussion.

Last step, which is trivial since it's open source, but it's probably best to say, you're more than welcome to engage. If you have the expertise and understand what's going on, provide a solution yourself. Rather than file an issue, provide a PR. Or if you filed an issue and the maintainer told you, oh, you know the problem is here, is fixed this way, you're more than welcome to provide a PR that follows the maintainer's indications. You don't have to wait for the maintainer to fix it. Now, if you don't have the expertise, instead to code, also one way you can instead contribute is to test the new feature and the issue that maintainer fixed for you right away. So you can really support the maintainer on saying the issue is not an issue anymore. I fixed the problem, we can move on with our lives.

Also, give the feedback right away. Just be silent and say, okay, I'm done. It's not enough. Maybe just a simple comment on the issue, say, thank you man, you fixed that in version 1.2.3. It's absolutely enough, but at least you let them know that everything's good, and then move on the next issue. And one final step, don't forget to thank them. Okay, folks. Once again, we are, and you are if you're also a maintainer or if you will be a maintainer, we are still people. We rely on kindness, okay? Don't forget to thank people for the time they give you. It's not that the maintainer will thank you for the issue that you filed, and you will thank them for the issue that they fixed.

It works like that. Like you usually thank people when they hand you over the salt, or anything like that when you are having lunch, okay? Don't forget it. That's very important.

So, that was a brief overview on how you can support your maintainers. Let me summarize for you. Kindness, first. All the times. They don't owe you anything, and it's always good to be kind when you're requesting people to help you. Support them, be available, eventually contribute if you can. Engage, and once again, manners and kindness, and thank them. Once again, kindness is the keyword.

And that's why, as I usually do in my talks, that I like to finish my talks with a famous quote from somebody way, way, way wiser than me. And today, I choose Aesop, the Greek writer that said a long time ago, I'm talking like 2,600 years ago, or something. No act of kindness, no matter how small, is ever wasted. We always remember about received kindness, okay? Remember that. That's it, I'm done for today. Thank you very much, once again. I'm Paolo, NodeTSC and principle engineer at Platformatic, and it was lovely to have you today here, listen to me. Thank you very much, and bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye.

Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye.

Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye.

Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye. Bye-bye.