About the talk
RailsConf 2019 - Maintaining a big open source project: lessons learned by Leonardo Tegon
About a year ago, I started to maintain Devise - one of the most popular Ruby Gems available. I had no knowledge of the code and a little experience with open source from a side project I developed myself.
Obviously, this was a very challenging task and I made a lot of mistakes in the process. The good thing is I learned a lot too.
In this talk, I will share with you some of the lessons I learned that I think can be valuable not only for open source but for our day-to-day work too.
High 2 years ago And this is the most recent picture of her team and if you zoom in little bit, you're going to see me. I right there. Don't ask me why they look So Satisfied in this picture cuz I had no idea. Anyway, this is how we can find me on the internet. And so if you want to follow me at 6 want to give feedback on this talk, that would be really appreciated. Anyway, you might have heard of us are open source work about the farm attack is known for some ruby gems, like devices support form and also the possibility to
work on those jams is one of the reasons that made me want to drive the company in the first place. But when I got there most people that those projects and the church's we get paid by clients rights deliver projects. So most people that do in their spare time, which means that people left the project became inactive so issues in pool request will sit there for weeks without any response and I wanted to help but I didn't know where to start. He was only the Rubicon for
Brazil 2017 where half our plans are give a keynote about the future of the Ruby community and he talking about Ruby's nautical new thing anymore. Everyone everyone. Just just want to talk about Golden Elixir or rest or something. And so the question was what their future damn. Well, he said that the future of the Ruby Community is brilliant, but it depends on us and basically he was saying that everyone can help we can do open sores. We can write blog posts about cool things. We learn we can organize in a
tensile local meet-ups or you know, you can just talk to your calling and share something cool down and work. Those are always to keep the language interesting friend of developers and to give it back to the community. Softer than a decide to do it and decided to one thing two devices gym, and just so you have an idea. This is how things look like at that time. We had a bunch about 250 issues and 51 per request. And this is how things look like now, which I believe is way better. Thank you. So there is I'm here today is to share my journey
with you and the things I struggled with and the mistakes that I made in the lessons I learned from them. And to tell you that if you ever wanted to contribute to open source, but you're not good enough. Hopefully my story can convince you otherwise and hopefully I can convince you to go ahead and try it is known that the first person that can tell to you is that you are good enough. I really think that anyone can do open sores. But I do know what it's hard to start. Right and part of that I believe is because we think we have to go to help we got understand like the whole corn days
before you can do anything, but I think the quickest way to start a to-do issue triage. What does that even mean? Right. So triage is the process of examining problems in order to decide which ones are the most serious and must be dealt with first. And for open-source Disney's ensure that they should follow the recommendations from the projects contributing guide. Do some projects have it by like this one contains guidelines on how to contribute Sandra party issues to that project. So for example on radios they ask you to send feature request to a mailing list.
But we do except speech request on the advice of those things will be different and depending on the project. That's why I recommend you to read that file before you do anything else and if the project doesn't have one of those like you can create an issue unless. That will be a great way to start contributing. So here is what divides that's for contributors when reporting issues include the title and a clear description as much relevant information as possible and either at SK are simple raised up that face the issue and it said that because it's hard to fix
books without information right? It's kind of like when someone says our site's not working like one of the first things we ask is switch browser are using In device, we also ask for your faintest case because we want people to try to reproduce the issue in an isolation. This means without any other James just divisor and we say that because the most common cases expected to be working since we have fast for it's right or at least we hope so so a lot of people are experiencing the same issue chances are he's been caused by a combination of
things that that is very particular of their application. Say is not a people can find out what's wrong the combination of things that's causing that issue. And this will give us a better direction of where to look at it. So, that's the first thing I did. I just looking for issues that we're missing information and we'll ask the afternoon to send it and then I would just add this needs more information label. I just want to give a side note here. You can probably see that I've replace it disperses handle with the
GitHub ghosts user profile. If you want to we can probably just find out who they are, but I asked you not to cuz I don't want to expose anyone this talk. Is it easier for me to talk about things that really happening to show you the lessons that I learned but I do want to talk about situations here and not Angels. Okay. So two weeks after I asked him for that information. I will look for your shoes with Denise Marie for label that didn't have any response and just cause then I know two weeks is when I'm sure value but it seems like a good time spent for people to
come back at us. And if they haven't yet, maybe the issue is not a priority right now or they couldn't reproduce in isolation. And another thing the device contribution guide says he's opening a new wishes to ask questions. Please go to the projects which documentation and search good first or try to ask your question as to cover flu and I want to say that it's really important to ask questions, but they should strike. It may not be the best place for it and I say that because the only people that receive notifications in their argument anus and
the Watchers and others or they shoes so they're probably not going to answer any questions which leaves does weed amount a nurse that are usually there is not much people in a few people. So like if you open is what's the question of the Verizon wait just for me to answer is going to take awhile. So that's why you were you say that it's better to ask him to be far as like stack Overflow. But again, this is going to depend on the project. I know that some projects accept as well for them
to use mailing lists are farms just for this. So you guys going to the pain of the project so I didn't look for your shoes that where he'll pick waxing cause then and I do a lot of this in the beginning but this is something I've been trying to do differently lately because when I realized the person might be a beginner I try to give them a better nicer is easier after some user experience a to forget how we was like when we started right, but I do remember I was afraid to ask questions of work. I was afraid to stop the
stupid. So I think it takes a lot of courage to ask a question, especially in public fire like YouTube. The one that first experience to be this hurt this bad. So when I can I give them about an answer like once I'm someone open an issue saying that they were not seeing the flash message in device, and I know the rails doesn't show them those flash matches by the food that you have to do it in your application. So I answer explaining this to them and I wish I could do this more often, but sometimes we just can't say no because there's not enough time and some help you? Olympics did
this one? So what I'm saying here is that you should triage is a great way to start I could like this made me feel productive very fast, and it doesn't require any previous knowledge of the code base and after doing for a while, I get a lot of context of the project and they couldn't play problems. He was facing. And if you do that, you'll get to know how to work in Tacoma Cuesta questions. They ask on the issues in to request which you probably help you in the future when you start sending patches for them. I highly recommend
you to read Steve klabnik blog post. He explains how he started doing issue training reviews and one interesting thing. That's he says in his article. Is that easy to do with 15 minutes per day and he wants to do it before leaving the off Siri or after lunch. I actually do it a lot while waiting for SSDI. So now, you know how you can start to know so how to do it without spending a lot of time but now you might be saying but I'm not a maintainer and I got to tell you the only thing you can do is click on the merge button. So seriously, you don't
have access to their friends, but you can still do we should she has the same way that that I do and as a matter of fact some people ready to do in this device like this person who asking for a stump replication and his other one who acted a couple of questions to try to fly to fire weather issues and this is just an example of how we can start contributing. There are so many other ways to start help like review / request so you can look for possible issues and pull request as precise because honestly if I see if we request that doesn't have test that's the first thing I would do
anyway, Newcastle test dissolution this one is very important because if we're experiencing an issue and like Father prayer request for it just tested that's the code tester application when that cool to see if it works and coming back into pool request. What's what's which will watch you have fine like this. This will help them attain is a lot just to have a confirmation that the issue is actually happen by second. You can help reduce an issue sure what you have found in the in the issue page solution. This can be writing blog posts are some questions. I start over clue
are just you know on the guitar abesha Striker you should like if you know the answer like this person did just share with the community. Cuz when I started I struggled a lot with Device that's which I spend some time with corporate have to run tests and specifically raising Ruby versions. So after a minute to get it working, I want a piece of documentation are with me and I hope this will help others and that we should contribute to that project in the future. So those are all examples of how you can contribute without having to write code because from you about
helping people and there are a lot of ways to do it that don't involve writing unicode. That's great. But now you might be wondering if we're just asking for information revolution steps and stuff what happens when they do send us debit card information. So it's time to reproduce the issue and it can be around a felon Teske's or just follow the reproduction steps. And once we confirm identity issues happening, it's time to understand why because when were you going to do next depends on the issue is a regression which means it is it to work on a previous version we can
use the gift by sex comments to find out which company introduced the Denver Gresham not go into the details of bisexual, but I do recommend you to read Json Draper's article explains very well how to use it. But sometimes we are after a no issues in of things that never were working before. And for me, this is kind of flight when you join a company and they give you a ticket to work on without any kind of from wording and it just spent a lot of time in a dive into the cold messing around to see what's happening. And so for me one thing that's being in
the woods, but I wanted to share a couple of articles with you because before I have to dive into the virus code that was mostly a poster booger. And so maybe those articles can help you get along with try to if you want. The first one is dead bugging radios with pry and the second one is to get Labs private booking guide. Another thing that I really recommend you to read this reading you from your work search by Alicia Keys, like looking at unit test, for example, because they can service
documentation. Tell Lena telling us how it goes behaves in different situations. Okay, great. So now this is all to find out the code that's cause an issue. But what happens when when we do find it code? And I think is always hard to understand a piece of code that we're not using to my calling you home. She wrote something that I think summarizes this feeling very well also read a piece of code for the very first time. We are Merced Inn along learning curve and a continuous cycle of question is that with any sites? Basically, this means we started from This makes no sense.
They could just have dinner done ax instead. Which witch is which we have no context of the code, right? The only permission to have is the date you was committed in the person who did it. Like there's one situation like to share with you made it known that someone reported an issue saying that it was possible to create records on the database during sign up the volume issues have failed. You probably know the feature where device keep some stats about the user like the number of times. They have signed ending or something. It
turns out that when we do that we can order validation. And so someone send a request which was literally one light change. So just look like an obvious change. We considered a quick fix and margin and releasing in the minor variation. What we didn't predict was that this has been the coldest forever applications. I rely on his behavior. So once we change it things started to break we got one two, three four issues. You got the idea since we started dating the user invited users were not being able to see any more.
And has made me realize how we have limited vision of the word. We make assumptions based in our past experiences, right? Because you know, there is applications. I work at before interest me. There were a lot of them. We would try to have his mother in camera Ferrell. Dismiss that was already considering you're holding back the change when we got the following issue. So basically this person was calling an external Services inside of an addition come back and do serve a charger then put a request. So since we started validation the
model in a place we were not before they got they got a big deal out of it. So just made me feel about for rights in actually reconsider what it was doing because clearly I didn't have like enough experience to handle this and because of that someone just spent a lot of money. And I want to tell you in those situations. It's easy to feel overwhelming. So the best thing we can do is to talk to someone else and ask for advice. So I thought I was talking with some colleagues another open-source month in years and they all agreed that it was better to roll back the change
because I'll do we couldn't predict that a lot of applications were William this Behavior. This kind of change should be done in a major version, right? Choice of the original issue with another solution and remove the validation request in a place you can control out of validation complex in places. We don't know like inside the responsible when we are at the beginning a production issue or indirect ask when we are getting any matches. I just met someone you drive between me and you know, they might introduce code that runs does validations without knowing
about it about the side effects and Co review and test may not always prevent do Spanx. So this brings us to my next lesson, which it's okay to make mistakes. It's okay because we can literally lot from them. And when we do make mistakes, I believe we should focus on the future instead of the best. So this means changing the question. What should I have done to? What can I do from now? Because up to this I was way more careful with change that could break backwards compatibility. Now I think in ways that the cold could break existing application that I wouldn't
before. Mistakes made me grow as a developer Amazon. Another thing that I want to tell is that after that incident I decided to look for the comet messages that first introduced said that validate false called. I don't understand. Why was there in the first place? So this was not much help you but it made me realize how old is called was. This cold was 9 years when we accepted the request. And is bringing this brings us to the next lesson I learned which is
documentary decisions because we cannot trust him or memories. Yeah, it would be great to ask the elders every time I have a question, but if we can do we can ask them they may not remember I mean, would you remember the reasoning behind a Kuduro 10 years ago? I certainly wouldn't so that's why it's important to document the decisions like why we did something and the other options to try because the code to self is not enough to show is the big picture. I think one of the best ways to document vestiges is inside keep coming to messages. So if you haven't yet, I recommend you
to read this article to give some great tips on how to write a good, two messages like which questions it matches two should answer. For example, why was just change necessary and how does it solve the issue? Another school that I like a lot is how to write a gift commit message by Chris beans on the folks Morgan destruction of the message and purple some guidelines to write messages, which is also very interesting. So for me what a Google message message looks like is this we have a brief summary that explains what what was changes and the details
give us context of why this was necessary. It also gives that this can be removed else will drop support for a raise for No, another thing that I learned this from that body they shinny shoes and also others that we had is that cold is expensive. So that one line for request cement in Austin us Innocent, but caused a lot of trouble and for open source libraries on swear the public API, you can only remove it in a major version. So we have to be careful with which cold winter this to the library.
So basically now I want to request when this happens. And when I say it's okay, it's okay. But really when I review featuring Quest now, I started to ask some questions like is it usable for it? Is it usable for an applications? Is it an edge case? Cuz if it is maybe he's not worth it added to the library. Is it flexible or is it too complex All Those Questions help me to understand whether the cost of the code is worded or not. And then I stream the last thing I want to tell you is that if you're going to do open source be
nice. No because a lot of people had bad experiences and I know that some papers some people are rude disrespectful in me. So it's important to have a code of conduct in the repository to ensure that everyone has their a harassment-free experience. Enzyme cleaner make sure to act in cases where this code of conduct is disrespected. I also highly recommend you to read this book nonviolent communication by Marshall Rosenberg strategies for communicating with others and transform potential conflict into peaceful dialogues are just amazing.
What is summary? What I try to do is respect other opinions, no don't make fun of people just because they disagree with them as much as I can before jumping to any conclusions. Then to have been put to because I don't know that person what they are going through. For example something that can be causing someone to communicate aggressively are deadlines and productive production outages do situations cause a lot of pressure and depression can be easily passed the law. So for example one time someone commented the following in an issue.
It is a butt but seems like that and let the bug affects many people no one cares and all I can see in this in this comment was Ben. No one cares part was like really do know how much time is spent. It is like my spare time. So very upset in a little bit. So when does minutes No, he's actually talking about waiting 5 minutes before we disagree with someone on an idea. But if this works very well for situations when I'm angry too because it's easy to be rude when we just heard something that made us feel bad. But if we wait for a while before Speak doesn't much as my begun.
And I should have heard me what's has been working better and just so give it a date because then I have time to fill my mind with other stuff things that I like to do like pressing sports or dancing or just spending time with my family and friends. And the good thing about this is this is that it also gives me time to understand the situation better. So in the case, I mentioned in the earlier the person felt like no one cares because they posted a comment in a issue and no one responded, which is terrible. But the problem is that issue was closed it and I
usually can't keep track of those. So I just answer than explaining why this happens it's hard for me to keep stray cats all the notifications. So we just work works better to show up in a new one. It will definitely going to have my attention. Okay. So another thing that I want to say to you is if you're going to the Des. Take care of herself, you know and what I mean by Jesus, there's always going to be another issue to work on or another Peru Quest 2 review. So don't feel guilty if you can solve everything. And rely on tomato juice to help you to do the job.
Like issued same place. I can give people a better direction of what the project aspects of men regarding information and everything. So we probably don't have to do much issue triage with this. And another thing that I use a lot is GitHub save the replies because you know where to find you a bunch of issues can get boring and this help us to do Which Wich. Faster Another thing that's very useful ways to stay about the you know, it would automatically close issues after they went there for a while and the cool thing about this one is that if someone comments on a cousin issue you
actually open up for you. So that's nice. And finally I ask for help because it is it to feel like we should know everything, you know, since you are demented of the Jan you got to know everything but we shouldn't and most importantly week so ask for their start of blunder open-source Montana's for help us you're calling for help and finally has Nicki Minaj for help. Just something that I took me I wire for due to do it. But you know, I have an example for you like when a user from the security screen device and I created a patch for it with we merge it
and move down but someone asked whether a CV was created for this. No, I have seen savjz around before but I didn't know exactly what they are and I had no idea of how to create one, but I wasn't Shakir about saying using tissue. So I should I search the internet and the only a certain amount play there when I was able to request one. But it turns out the person who asked it is with learning which words that hackerone and was able to help us to get the TV. So if I have been honest in the first place, we will have God that
way earlier, so don't be afraid to ask for help. It's okay. I also thank you again for helping us with this. Another important thing that I want to tell you that show your company why this is important because it is hard to do it in our spare time and we don't want to do it this forever. So some things you can tell them is that why do we open source? We learn a lot of stuff right? Just give us the opportunity to write blog posts and give talks. And those things help with a company branding and also we're developers to their team.
Open source also helps with motivation. So we know that working on the same thing over and over again can get Bari. So if they let people do open source part-time this can help with their motivation and can also decrease big turnover ratio. Why you doing this? We also learn a lot of stuff like raising theranos how to write commit messages all those kind of things and those who help with your professional development. Because of all those benefits some companies are already doing things like OSS Fridays, which is a way to let people work in open source without
having to do it in their spare time and we were able to get to eat. So we still got to do it after work, but at least, you know, you'll get paid for it, which is better. So this is basically my story if that's not much interesting to you what I want you to take out of this Takis. You don't need to go to help like there are plenty of other ways to do it when you do it. Menu decisions because other contributors and also your future self will be grateful for it be nice and I'll be respectful and finally ask for help, you know, don't try to solve everything alone the
communities there to help you too. And also if you want to start doing this and needs help you free to ask me to because I know I had a lot of it I had help from his that who helped me to start by showing how to do issue triage and I have help from her spell who reviews a bunch of to request and it was there to answer difficult questions like Things about semantic versioning. I never got the one right and Leslie last but not least from my former calling Philippi who has been my partner in the simple Farm gym. His actions at 1.
Come visit me to start Montana devised and also to give this dog so probably have not have done any of this without him. So, I just want to say thank you to all these people and to everyone to contribute to device and also to you who can hear to watch the stock. So, thanks.
Buy this talk
Access to all the recordings of the event
Buy this video
With ConferenceCast.tv, you get access to our library of the world's best conference talks.