 Hello, all right. I like to walk No, thank you. It's a huge honor to be here today. I've never been to Singapore before So this is my my first chance to visit my wife and I are planning on sticking around this weekend and exploring a little bit So we would love any any recommendations So I'm a developer at github I work on Ruby Java scripts and kind of whatever else needs done to to work on product features most recently I finished a project kind of Re-vamping github wikis a little bit. I don't know if you've used them recently. They've gotten a bit better And then right now the project that I'm working on is actually upgrading us from Rails 2 3 to 3 Which is like five years late So, but we're close. We're close. We'll be on we'll be on get on rails 3 soon And then 3 1 3 2 and 4 before too long. So anyway, that's what I've been working on You can find me online as beekeepers both on Twitter and github I'm not a garden gnome despite what that suggests But if you have any questions throughout this or want to get in touch feels feel free to tweet at me We'll probably have some time for questions at the end, but if we don't get to them. I promise I will reply on Twitter So about seven years ago My wife and I bought a house and we planted our first vegetable garden It was in our backyard. It was small not very ambitious. We had no idea what we were doing But we kind of wanted to experiment with it Each year we've kind of continued to do this and continue to expand This is actually the a picture from like the second or third year that we did it We built some nice boxes Started kind of scaling things up and over the years I've realized That what I like about software development what I like about the software development process is not the engineering side, I'm actually not a very good engineer But I really like the gardening side See software really isn't like this like Predefined prefabricated product that like goes through this like nice clean process and comes out at the end It's really more of an organic process like you your job is to to create the right conditions for this thing to thrive And then as it grows make small adjustments and try and shape it into Something that eventually hopefully produces fruit And And ideally with that fruit then you you have seeds that you can then go on and and plants and other products and use them in other ways And so I've been thinking a lot about this the last year or so and And specifically with as it relates to open source because I mean gardening alone is awesome You get you get all of these things you get you know nice fruit that you get to eat yourself But it's even better if you can share it with other people Especially if you can share the harvest So a github over the years we've actually done quite a bit of open source And I would say if we're honest about it lately, we haven't been that good at it I mean we're still on rails to three which means that we can't participate in Making rails itself better. We have some projects that we haven't haven't been the best caretakers of So at the beginning of this year, I kind of made it one of my personal goals This is something we need to get better at there's something I want to do better at myself And this is something I won't github to be better at So I've kind of set out on this journey this last year And I want to talk today about some of the lessons that my love for gardening has been teaching me about maintaining open source And so today we'll kind of walk through the process of gardening As that relates to maintaining an open source project and kind of ultimately my goal is to convince all of you To go out and start your own gardens to go out and release open source and learn what this process looks like So before I do before we dive into this process, I want to talk a little bit about my experience My first open source contribution was in 2006. I was shortly after I had started using Ruby and rails and Recently well over the years I've contributed to whatever projects gems and stuff that I was using but I've never really been involved in a Large open source projects. I've submitted some patches to rails here and there but never You've been extremely involved Recently, but my most well-known project is dot-env. It's just a really simple thing that will Load up configuration files into the environment when your app bootstraps. It's not very complicated In the past I was the maintainer of delayed job for a long time. I didn't originally write it It was written by Tobias Luke key from Shopify But at the point at which we went from rails one to two when two started supporting gems He didn't really have any interest in maintaining it. So I gemmified it and then supported it for several years After that I worked on a project that probably nobody's ever heard of called Q Which is kind of an abstraction of these database Q idea where you can swap out back ends My first gem ever was called Tinder. It was a campfire API before campfire actually had an API It would just do screen scraping um My only non ruby project that I've kind of actively worked on is called Rosie. It's basically factory girl for JavaScript and then recently my kind of Pet project has been this github notifications client Because I hate email and get a lot of github notifications. I'm trying to figure out a better way to manage them So this is where I'm coming from. I mean none of these projects as you can see are huge None of these are rails, you know, they're not it's not ruby These are all really small projects actually And so I would say, you know, if I had to judge myself as an open source contributor, I would say I'm average I'm not prolific. I'm not a beginner. I'm somewhere kind of in the middle And I say that means basically to convince you that this is something that all of you can do So we talked about large open source projects, I would actually Argue that something like rails is actually more like farming. It's not gardening It's at a much bigger scale than that Or, you know certain projects Might be a little bit more like land management where you're just trying to make sure that things don't fall apart and burn down But you don't necessarily have control over the process So specifically today, I'm talking about gardening. I'm talking about these smaller projects That we all use it in and out on on our apps every day So before we dive into this a little bit more I do need to give some some credit to Steve Klamnick. He posted this great article How to be an open source gardener. I would highly recommend you go read it His was his was at the perspective though of diving into one of these really large apps You know, he got involved in rails started kind of tending kind of some of the issues And so anyway, it's a great perspective. I would definitely recommend reading it But I want to clarify that this is not actually the perspective that I'm coming from I'm talking about smaller gardens than this So before we dive into this I just kind of want to get an idea of where you're all at show of hands How many people right now maintain an open source project like you are the maintainer or one of them? All right, excellent. Keep your hands up. How many people have committed Contributed in some form to an open source project Even more. All right, excellent. Thank you So before you dive into any gardening project, you need somewhat of a plan. It doesn't have to be perfect but a plan will at least help you kind of avoid some common mistakes and When you start that out, I think the important question to ask is why am I doing this? What are my motivations? I think there's some myths about open source and what it will gain you You know, some people think oh if I just put this out somebody else will write the code for me Somebody else will do the work And if you if any of you that have maintained open source I've experienced this you know that that's not usually the case Most small projects hardly ever see a real contribution But ultimately I mean our goal has to be to produce fruit right we want to make our projects better we want to Create things that other people can use We're all driven by this desire to create things But I think there has to be something else that sustains us and that and that is this this ultimate goal to produce a better product The second question we need to ask ourselves when we're getting involved in open source is how much time can you dedicate to this? Because it takes a lot more time than you think it should and the weird thing about it is So there's large large open source projects seem to be the ones that you would expect to take up more time And they do take a lot of time And they're hard because so many people care about them, but smaller projects are kind of the opposite They're hard because nobody cares about them. You're the only one and so you have to spend all of your time tending it So that's a that's the planning phase just ask yourself some simple questions Now we're ready to actually dig in and start doing some of the work When you're ready to release it there are a few things that we can do to create the right conditions for this project to flourish And in gardening we call this cultivation You're preparing the dirt. You're fertilizing it So that the project can actually take root So for an open source project you want to make it as easy as possible for people to contribute and use your project Any small barrier to that any small hurdle could be enough to discourage somebody from actually contributing So let's talk about what some of those things are the first one seems obvious or silly But pick a good name The name of your project can actually make or break it And so what makes a good name? This is not a complete list, but these are kind of the things that I've been That will run through my head as I'm getting ready to release something first It has to be searchable if it's really generic. It's hard for people to find it It needs to be memorable So those two are kind of at odds if you want something to be searchable You need it to be unique But you also don't want to be so unique that nobody can remember what it is And then you need to be suggestive like what it needs to suggest somewhat of what this project actually does It can't be completely unrelated And then on the the knot side it can't be too boring Organ it'll be hard to find people won't care about it. It can't be too weird It'll be hard to it'll be hard to remember and also not too trendy like if anyone wrote a rails plugin back in the day there was the acts as whatever trend and now Nobody writes plugins named acts as whatever so be careful that your name will actually last for a while So as an example of this I mentioned my my project called Q. I think in terms of The the quality of code. It's probably one of the projects. I'm most proud of But nobody's ever heard of it. Nobody's ever used it because they can't find it it's really hard to search for and People can't even really pronounce it. They're like Q you quick Huh? So when I was showing this to a friend initially I was trying to explain it to him and I'm like, you know, it's just oh my gosh. It's a better background queue That's all it is. So I came up with this idea like oh, I should have called it omg bbq So I'm gonna rename it. I Claimed that name on Ruby gems recently so that nobody else could steal it But we'll get ready for the marketing push soon But I think this is a good example of a name like it's kind of fun. It's playful It's not too weird because we all know what it means at least somewhat depending on cultural barriers But I think this is a good example The next thing we need to do is write documentation TJ talks about this a little bit ago If you want people to use your code or if you want your project to thrive You need people to use your code and if you want them to use it They have to be able to figure out how and that's docs. So docs are not as fun. They're not as sexy They're you know, it's not as interesting as actually writing the project, but it's still extremely important And a little bit of documentation can go a long way So probably the most important part is the read me at least if you're putting your project on github This is the thing that takes center stage So I want to talk briefly about what makes a good read me because I think that this is probably the most important part of your documentation So first we have a one-line description. This is just a project that was on the github trending page recently So I completely picked it at random simply that it was like the second thing on there So you have to have a quick one-line description tell people what the heck this thing does and why they should care It should be clear. It should be concise should have some of the key words that people are looking for But not so long that they get bored while they're reading it That's what the second line is for a little bit longer explanation This project chose to just do a sentence or two Some of my projects I've done like a couple paragraphs to explain the motivation behind it or why it's different than than some existing Thing that's out there After that we need to tell people how to actually install it again This depends on the project if it's a ruby gem just say gem install the gem name or add this to your your gem file If it's something else, so this is a JavaScript library. They say hey just include this in your in the header of your page But showing people how to install it is an important next step We need to then tell people how to use it and this should probably be the longest section in your read me It should kind of outline all of the the different options you know give an overview of the way different ways that people can actually use the project and Then finally all the way down at the bottom You tell people how to contribute because the goal is that you know the first time somebody comes to your project They're gonna start at the top of that read me, but over time they're gonna they're gonna work their way down right eventually They'll install it eventually. They'll use it and The only way that your project is gonna thrive then is if you can help them become a contributor So at the bottom include that information. How do I get the source code? How do I run the tests? How should I submit a pull request? Do you want pull requests or would you rather you know me email you a patch? I don't do people still do that. I don't know maybe not But tell people how to contribute If you want some examples of good read me's I said I went to the trending page. I would recommend starting there I've found that most of the projects that show up there are there because they've done this one thing well They've they've documented their way their code in a way that that is engaged people So look at those examples Next I'm not gonna spend a lot of time on this because this is something. I don't care a lot about what it is important You have to choose a license If you don't have a license on your project then the assumption is that it is copyrighted by you and nobody else has permission to use it But there's also like weird legality things there that I don't understand But I'll basically just choose a license If you need help with that choose a license comm is a pretty helpful site that will kind of walk you through the like couple basic ones So start there And then lastly for for preparing your projects You need to just simply follow conventions of other projects if you want people to contribute then they need It's helpful if you can have them do it in a way that they're already familiar with So if it's a Ruby app follow Ruby conventions if you know have an app directory if it's rails have a lib directory if it's a gem Have your tests mirror your app or your your lib files Which seems kind of silly, but then it is actually really helpful people can easily dive in You know have a gem file have a rake file whatever it is those conventions are there for a reason But mostly it's it's easier for people to dive in But if you're gonna make changes to your project now is the time to do it because nobody has seen it yet so the next step in Tending this open-source garden is we need now need to sew it and I think that this is probably what we imagine As we imagine kind of this glorious open-source life. We imagine that this is the main part of it, right? But this is actually the easiest part This is simply taking everything that you've already done and just putting it out there There's not a lot of work involved in this The only the only work required at this step is that now you have to talk about what you just did And I know for many of us that's hard. We're not very good at advertising the things that we do But you need to you need to advertise it say hey, I created this thing. Here's why it's important. Here's why it's good Here's why I think you should use it. I found it helpful to blog about it So I just have blog open soul org So here was my blog post about dot-end when I released it and it was just you know a couple paragraphs as you can see Here's why I did it Here's why I think it's important. It doesn't have to be slimy. It doesn't have to be You know deceptive as long as it's coming out of a place that's that's genuine People really appreciate it And then after you've blogged about it put it on social media I know that this seems like a silly game of trying to like get your thing on the top of hacker news or whatever But I think it actually makes a huge difference. So so tweet about it You know some projects if they make sense have a Twitter account That helps people follow it But we'll talk about it So everything we've done up to this point is really the fun and easy part. We created the projects We got it ready We released it and now is when the work actually begins And this is the part that I think most of us don't think about when we're thinking about open source Everything that wants to grow needs watered And it needs it consistently So without water plants in the garden will go dormant An attempt to survive drought the leaves will curl up and they'll eventually die if you don't water them So our projects are the same way we need to consistently water them And consistency is the important part In gardening they recommend that you water your plants every morning in the morning before it gets too hot This gives the plants time to draw up the water before the heat of the day But if you do it at night, there's a chance that there could be like disease Anyway, I found that this is actually really helpful advice for open source that if you Try and form a habit of not maybe not every day, but most mornings just wake up Check in on your project. Has there been any issues? Have there been any conversations? Try and keep moving the ball forward on several of those things Part of that is then also setting a guide for what it looks like to contribute to your project And I found it really helpful to follow your own contribution guidelines So if you tell people hey if you find a bug Open an issue for it. If you want to submit a fix create a pull request do that yourself It seems kind of silly. This is this is a pull request I made to myself on my github notifications app notice that nobody even commented on it by the time I committed it I'll usually like open a pull request and then let it set a day or two and then I'll merge it if You know if there's no discussion Again, it feels really weird It feels like you're talking to yourself, but I think it's really helpful for people watching the project to see what it looks like to contribute It also gives them an opportunity to jump into the conversation if they want to And that's where you have to start trying to invite them in Again, like it's really hard to get people engaged But there's often these opportunities where you can just say hey I See you commented on this thing I think you know or you created this issue about something that should should be made better Would you be interested in submitting a pull request? I'll do that almost on almost every issue that's open on our projects anymore I'll ask them if they'd be willing to investigate it and a lot of times they are sometimes they're not But if I hadn't asked they wouldn't have had that opportunity to participate We also have to always be hospitable on our projects and sometimes this gets really hard But by the time you see a contribution the author has usually spent a couple hours either getting familiar with your project or Investigating the bug or the issue or figuring out how to build the new feature And so whether their contribution is something that you want or not you have to be hospitable to them You have to be courteous You know some of these some of these contribute some of these contributors are extremely ambitious But maybe their contribution doesn't quite meet your standards So you have to tell them that you have to give them that feedback say hey, I really liked this I usually start out by by thanking them for their time and their energy say thank you for give for working on this and Then I start to give feedback and and usually it's in the form of questions Like if I just tell them hey, this is not good. This is not good. I asked them say hey Could this break in the future would maybe it makes sense to have a test for this Or what do you think about this other thing somehow engage them in a way that that brings them into the conversation even more When you're patient and courteous with with contributors, it'll eventually start to snowball They'll do that to other people that are participating in the conversation And they'll also do that back to you Now there's there's times too where even after this feedback cycle like things still don't quite meet your standards And I kind of I liken this to like our every once in a while our niece will come over and try and help us when when we're gardening You know and she'll like start digging something and obviously she does no idea what she's doing She's doing it horribly wrong, but I still need to honor that she's interested in that and that she's she's putting some amount of effort into it And so in the same thing with open source, you know if somebody has made their best attempts to try and contribute Sometimes sometimes you just need to merge it even though it might not be the same merge their pull request and then come back and fix it up later and then most importantly with with Disgardening metaphor is you have to give it time And an open source project is no different as soon as you plant the seeds in the ground It seems like nothing's happening. You'll spend weeks maybe even month or more and see no progress But as long as you can keep doing it consistently eventually you'll start to see see things grow So as your as your project starts to grow there's actually countless forces that are trying to destroy it And it's up to you to defend against them So in gardening you'll actually take in you'll cover the soil with mulch So either wood chips or or grass or something But the idea is that you're trying to protect the plants and the soil from these forces so it could be weather It could be weeds You know it could be erosion So we have to wait to figure out how to protect our project The first thing we need to do is only add features that you want to maintain And this is probably one of the hardest things with maintaining a project as soon as you have somebody interested They'll submit a pull request and you're like excellent And then you realize that it's not something that you're remotely interested in Even though they think it's extremely important They'll you know they might kind of go back and forth with you and say oh, this is why I think it should be If it's not something that you want to maintain then you simply should not merge it this has been a Probably one of the more painful parts for me in open source is you know somebody will submit a Pull request for a mongoid adapter to queue and it's like well, that's great But I don't want to maintain a mongoid adapter because I don't use mongoid And you don't want me to maintain a mongoid adapter Tests are extremely important in this process As people are submitting contributions, you need to know that the things that they're submitting actually work And and so having an existing test suite will will give an example of how people how people should contribute Not only does it give you confidence, but it also gives confidence to the people submitting these things so Travis CI is Incredible if you haven't used it I would recommend on every single open source project But the great thing is they submit it they open up a new pull request the tests will run and they'll know right away And you'll know whether their contribution is is passing or not Now the hardest part Don't feed the trolls There's gonna be people that will not be happy with your project no matter what you may be the nicest person in the world to them And they will still be extremely upset Try not to engage with them. I mean say thank you Be be courteous as you would to any of your other participants But do not try and aggravate them TJ earlier was talking about the the hearts thing. I tried that with one Contributor that was not very happy. I kept posting hearts and eventually I got an email from him that said just stop posting hearts I don't love you. Oh So I actually went back and took the hearts out and I think I replaced it with like I like you or something like that I don't know he didn't appreciate it. So I learned not to feed the trolls As your project grows eventually though, you're gonna mess up some of those things. We just talked about you know mulching is not enough There's gonna be weeds that are gonna start to grow. There's gonna be mistakes that you made and so we have to prune You have to remove features that have either Kind of gotten unwieldy gotten out of hands or things that kind of evolved into something that you don't want to actually take care of So so remove any of those features that you don't want to maintain that slipped in there I found it helpful to split them into separate repositories So like the Q project that I talked about If somebody submits an adapter that I don't want to maintain I'll just say oh well you can publish it as your own and just name it you know Q dash Adapter name and then other people can use it. There's a nice plug-in API But I don't have to worry about maintaining it anymore One in one recent example of this I was on dot-end when I when I started working on dot-end The intention the entire time was to have it be development only because in production. There's better ways to set environment variables But development it's pain in the butt You got to like either set them on your machine and then they conflict with other projects or figure out some other way to do it But anyway over time people like oh, well here's a Capistrano Support for it so that when I deployed it'll automatically copy over my config variables People wanted multiple environments and it got to the point where I was like wait a second This isn't what the project was originally intended for So pull request 95 on this repo was the one that split out all of the deployment all the multiple environment stuff to a separate gem Now somebody else can maintain that and people that want that can add it But I don't have to worry about it being part of the core So the important part of with this use semantic versioning We'll first use versioning in general in your app I'm really excited about the the ruby core changes actually kind of switching to more semantic versioning ish Scheme but so semantic versioning is this idea where each of these the places in this this number are significant You have the patch number Which is basically bug fixes You increment that anytime there's a bug fix and only a bug fix Maybe sometimes like a minor feature, but yeah mostly bug fixes The second one is minor backward compatible functionality So whenever you add new features to it you'll bump that and then finally the third one is any incompatible API changes So to show what that might look like If you wanted to remove a feature you would deprecate it in a minor version and then come back later and remove it in a major Version so the ruby code for that say here's one vert, you know one dot x dot x of our project You just simply add a conditional in line It's like if you're using this future this feature, you know print out a warning statement That's just you know this feature will be removed in whatever next version And then also it's helpful if you if you include caller zero or whatever Caller line will will show the line of their code that is calling it that way They know when they see those run in their tests or in continuous integration. They know where it's coming from as you're doing this It's really helpful to keep a changelog So here's the changelog from dot nf And basically all it is is it's changelog md in the repo and I just highlight major changes That people will care about they could go I have I keep a link to the full changelog That's actually the list of commits, but I think it's helpful as as the maintainer to roll those up And highlight here's the features that you'll actually care about so then the whole point of all of this is To get a harvest And that's not to mean work at harvest like TJ No, just all right. That was lame. It's not as funny as Aaron's joke. I'm sorry She's not as funny as Aaron No, but the whole point of this process is to make your products better, right? It's the main reason we do it There's also the like, you know altruism trying to help other people make their product better But this is this is the point of doing it At the point at which it stops producing a harvest you need to ask yourself some questions First doesn't make sense for me to keep working on this I've had a lot of projects over the years that I worked on while I was actively using them And then at some point I stopped a delayed job was one of them I haven't used it in several years and so it didn't make sense for me to keep working on it And so give it away when it stops being fun find somebody that does care about it and it's willing to take it over The only caveat to that is don't do that if your product still depends on it This is something that we've we've learned the hard way at github We've given away several projects in the past that we thought we were done with And it turned out our product depended on them One example is it is actually the the projects I just got done working on was github wikis And wikis are powered by this library called golem Which about two years ago there was some people that were submitting some amazing contributions were really active on it And so we gave them commit access and release access They did a bunch of great work. The problem is we didn't keep up with it And two years later now golem itself had evolved to a point where we can't use it anymore And that's I mean that's good. I think golems gotten better But we were not we did not kind of a whole uphold our end of that bargain so Be careful when you do give it away That either the person has your interests in mind or that yet you keep a communication channel open with them You also need to clearly state the project status if you don't find somebody to hand it off to then let other people know That is no longer maintained The lesson that we learned this project on was grit grit is the Library that we used to talk to get from Ruby and For I'm since the beginning this has been to the to the outside world the thing we were using Except that we've been actually working on not using it anymore We've been working on lib get to and some bindings to these native C libraries, but we didn't tell anybody that So recently I submitted a pull request to grit that just updates the changelog Or excuse me updates to read me I don't know if you can read that but it basically just says great is no longer maintained Github's working on moving off of it, and you know, we're not we're not accepting contributions anymore And then I just went through and closed the like 200 and some open pull requests and issues With a link to that said hey, sorry, we're not working on this anymore If somebody wanted to pick up a fork of it, they definitely could So all of these basically come down to us learning from some of our mistakes And this is actually an extremely important part of gardening and maintaining open source I think a lot of us are afraid to get into it because you know, maybe our code's not good enough Maybe we're not very good at maintaining these things, but it's all a learning process And the only ways to get better at it is to actually practice it So earlier this year I actually tweeted for the record. I am terrible open source maintainer And a couple people like hit me up on this and they're like really like I've seen you doing a bunch of stuff That doesn't seem consistent But I think for me personally like it's not it's something. I don't feel like I'm good enough at And so I've been trying to work really intentionally at it But the best part about this is there's not like a world's best gardener There's not a world's best open source maintainer You just have to be good enough to produce a harvest if you be good enough to make your project fit your needs And so I think that's kind of the redeeming factor in this that There is no perfect So, you know, we should need to keep practicing. We need to keep getting better at this One favor I ask of you is if you see an abandoned github open source project Please ping me because I want to know I want to be a better caretaker of that or Explicitly say hey, we're not using this anymore Thank you very much