Video Summary and Transcription
Open source is a decentralized software development model driven by passion. Maintainers give their time for free, out of passion. Even a small act of rudeness can burn people out. Start with a detailed search when asking for help in open source projects. Providing detailed information in issue reports is crucial. Creating reproducible repositories with minimum details is the best way to get a fix. Follow up on filed issues and show kindness and gratitude towards maintainers.
1. Introduction to Open Source
Hello, welcome to Love Your Maintainers. Let me introduce my company, Platformatic, the best way to build your Node API and backend. Open source is a decentralized software development model driven by passion. It improves software quality, services, and people's lives. It resembles remote working but has distinct differences.
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 madness, 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 70s 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, free. It means free as in not paid, and free as in freedom is ambiguous. Not paid was obviously 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? 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 cultural backgrounds and capability, which means different points of views. In every aspect in the human life, this has proven to be an 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 a resemblance of 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.
2. The Human Aspect in Open Source
People in open source are driven by passion, not by money. Maintainers give their time for free, out of passion. Respect and avoid demanding attention in the wrong way. Remember the human aspect and avoid burnouts.
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. 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 simply love that you use their software. Otherwise, they will never have open source to eat. 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. You are not paying them unless you sponsor them. But that's a different topic.
Remember that action has 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 happens 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.
3. The Impact of Rudeness in Open Source
Even a single small act of rudeness can burn people out. Be 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.
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 Mantegna has seen nowadays. And people will burn out, and eventually will give up on the software.
Like, 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. Therefore, 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.
4. Asking for Help in Open Source
It never is a problem, actually. How do you ask for help in the open source project? Start with a very detailed search. First, check the issues. Then, move on to the PRs. After that, examine the code. Finally, consult the late documentation. If you have a trivial problem that nobody has reported, you may be using it wrong. We live in a distributed world with people from different cultures and expertise.
It never is a problem, actually.
Now, let's say we are kind. We are people which 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 it 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 dig 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 it specifically says that this problem will not be covered, because it might be. Of course, this list is after you already read the documentation on how to use the software, because I'm assuming that you already did it. In other words, please don't get somebody reply to you without reading the fucking manual, right? 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. Or you're dead. 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 I 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, with different expectation, and knowledge, and expertise.
5. Providing Detailed Information in Issue Reports
Never worry about overcommunicating. Put as many details as you want. Don't be afraid of annoying people with overcommunication. Maintainers may not have time to request additional information, so provide as much crucial information as possible. When reporting an issue, start with who and where, be explicit if necessary. Then explain what happened, what did not happen, and what is expected. Provide comprehensive context and narrow down the problem by reproducing it in the smallest way.
I'm not just talking about two persons. I'm talking in general. So, never worry about overcommunicating. 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 overcommunication. The more important details you can give, the better it is. Because think about this. Maintainers have their own life. So, they might not have the time to request additional information, and therefore will not process your report if they are lacking crucial information. So, do not be afraid to overcommunicate. And forget. And this will shock you.
Working on open source and reporting issues and investigating issues is like journalists. Do you remember the WH rules? So, 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 happens, what we are doing when that happens. Try to provide the most comprehensive context you 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 may be 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. We don't care. Try to narrow down the problem.
6. The Importance of Reproducible Repositories
Knowing the why in an issue is controversial. Over-communicating can distract maintainers and reduce the chances of your issue getting fixed. Find a good compromise between necessary and excessive information. Creating reproducible repositories with minimum details is the best way to get a fix.
This will return in a bit. Now, a 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 code base, 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 thinking of talking about over-communicating. But make sure you don't float maintainers with useless information. You don't have to worry to over-communicate, but you can't, of course, exceed. As they say in Latin, in medio stat virtus. So the virtue is in the middle. You can't pass tons of output or maybe gigabyte of outputs in an issue because nobody's going to read it. Also, reports with a lot of information will likely distract maintainers, which at some point 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 going to 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 I'll call reproducible repositories. So if you get a software and 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 mask 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. I'm not going to tell you how to create this thing, you can search it online, but the core is that minimum, isolated, public, no sensitive information.
7. The Importance of Follow-up and Engagement
It's important to follow up on your filed issues and provide all the necessary information. Engage in the discussion, offer solutions, and provide feedback promptly. Set up notifications to stay up to date and show appreciation towards maintainers.
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 and say, oh dude, is that a fix? Probably not. If the maintainer immediately asks for more information, you've 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're asking you in order to fix the issue. Also, it's 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. 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 versioning 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 the 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 is good, and then move on on the next issue. And one final step, don't forget to thank them. Okay, folks.
8. The Power of Kindness and Gratitude
Always remember to show kindness and gratitude to maintainers. They do not owe you anything, so be appreciative of their time and efforts. Support them, be available, and contribute if possible. Kindness is the key word. In the words of Aesop, no act of kindness, no matter how small, is ever wasted.
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 have given 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 time. 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 key word.
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, listening to me. Thank you very much and bye bye.
Comments