Attracting new contributors and making projects accessible to newcomers is an important issue to many open source organizations.
I will describe my experiences becoming a new contributor to open source. I hope that this will be useful to 1) people trying to improve the open source newcomer experience and 2) people who have never worked on open source and are interested in becoming contributors.
I've always wanted to develop software, and my friends told me that participating in open source is a good way to get experience. About a year ago, I started looking into open source projects.
During this time, I thought about what kind of open source project I'd like to join. I came up with a few criteria.1
What is the size of the project and is there a lot of activity?
If it's too small, there might not be enough opportunity for interaction. If it's too large, I might be overwhelmed.
Am I interested in the goals of the project?
I like number crunching and am interested in learning more about core infrastructure like cloud computing and networking.
Is there any formal effort to welcome newbies, like a mentoring group, newbies mailing list, etc?
I never felt like I could just jump in and immediately contribute, at least not when I was first getting started.
What programming language and tools does the project use?
I prefer to work in a language I already know and enjoy using, but I might be interested in learning a new tool if it sounds cool.
I had experience using FOSS software like Emacs, MikTeX, and Mercurial, but the projects that had the greatest appeal to me were the programming language Python and associated scientific libraries NumPy/SciPy. I'm excited about scientific computing, so I was interested in developing tools that I had previously used in scientific research.
I found out that Python has a mentoring mailing list, so I set my sights on contributing to the Python Core. But then I discovered the Outreach Program for Women and decided to apply for a free open source software (FOSS) internship there.
Applying to Outreach Program for Women
The Outreach Program for Women2 is unique in that the application process itself is a simulation of the actual internship. Applicants spend their time during the application period learning the tools and culture of FOSS, so that they can make their first contributions.
Therefore, applying to the Outreach Program for Women became my first experience with FOSS as a contributor. This isn't exactly the same as just "walking" into an open source project off the internet, since a program inherently has more structure and organization. But I still think much of my experience is relevant to the "open source newcomer" issue.
The application period was a month long and I thought that would be plenty of time to make some decent contributions -- wrong. I severely underestimated how much I had to learn, including:
Learning about over a dozen organizations that were offering internships in the program.
I couldn't work with all of them, so I had to read about them and try to narrow it down to a handful of possibilities using the criteria I discussed previously. Usually, I could figure out the overall mission of an organization, but if I went a level deeper and looked at the different components of their software project, I got lost in technical jargon.
Installing the Linux operating system
I was a life-long Windows user and had wanted to try Linux, but had never gotten around to it in the last 5+ years. Fortunately, my laptop is a Thinkpad T400 with an Ultrabay slot,3 which made it especially easy to install Linux distros. Still, it took 2-3 days to figure out how to partition my hard drive and install the Linux distros (Ubuntu and Debian) with the basic packages.
Learning how to "install" software in general
By install, I mean in the general sense -- not just installing things like Ubuntu and Devstack (the development version of OpenStack), but also situations like when you build a test environment and have to install lots of dependencies. Outside of writing and thinking about code, most of my technical problems had to do with missing dependencies.4 I learned to fix these issues by searching for the names of packages on the internet and in the bug trackers.
Learning specific version control systems and tools
FOSS organization use a variety of version control systems and tools, especially if they've been around for a while. I encountered Subversion, Git, and Gerrit (a code review tool built on top of Git). Fortunately, I had a little experience using Subversion and Mercurial, but learning Git on the fly is not ideal5 especially if something "breaks." One organization I worked with used Git, so I thought it was sufficient to learn Git, but I didn't know they also used GitHub to submit patches via pull request. This caused me a lot of trouble because I had cloned their source repository directly rather than from a forked repo on GitHub. When I tried to submit my patch, my Git push failed because my forked repo didn't know that my local repo existed. I had no idea how to fix this, and Christopher Lonnen, a Mozilla developer, spent an hour on both a Friday and a Saturday helping me -- I'm glad he was so generous with his time!
Learning the code review process
Submitting patches to fix typos or add documentation was straightforward, but if it was more complicated, I was lost. It's not trivial to figure out how to fit your work into a large code base. There were things I didn't know, for instance, that I needed to write or revise a unit test to go along with a feature/fix, or that I could submit incremental patches containing partial work. I was unfamiliar with code style guidelines like PEP8 and submitted code with trailing whitespaces.
Learning how to work in virtual environments
When it comes to helping newcomers get onboard a FOSS project, the focus seems to be on teaching them about version control and bug tracking systems which is great, but virtual environments are neglected. I found myself using virtualization tools like virtualenv and VirtualBox without having any knowledge of why virtualization was needed or how it works. It was difficult to find online tutorials on virtualization.
Getting used to IRC and FOSS culture.
Up to this point, I had chatted privately on clients like ICQ/Pidgin/Gchat, but I had never been in a public chatroom before. It took me some time to pick up chat slang like "np", "yw", "o/" and become accustomed to sitting on IRC channels all day so I could chase people down. But more than that, I wasn't sure how to conduct myself on a public channel. It felt unnatural and intimidating for the first few days, and that was even with nice people noticing me on the channel and welcoming me! Some anecdotes:
I had great experiences asking for Linux install help on #ubuntu and #debian. Assistance came immediately, so I'm very grateful to those communities.
Also, a huge thank you to Sumana Harihareswara of the Wikimedia Foundation who tagged along as my buddy to a (non Wikimedia) software development channel. I was nervous about "talking" to a bunch of strangers on a public channel and her presence as "wing woman" alleviated my fears.
Sadly, my first day on IRC, I had an interaction with a male that I would classify as "marginal stalking." I informed the operators of the channel, and they dealt with the matter swiftly. It bothered me a little, but it would have been much worse if no one had been there to take care of me.
Another obstacle was finding things to work on. For the sake of the application process, some organizations would come up with "easy" bugs for the applicants, but I'm not sure if this is the norm. I recall that when I tried to work with OpenStack during the application period, they had no idea where to find easy bugs, at first.
I had (what seemed to me) a great background for getting into open source -- strong technical experience from studying science, lots of software user experience (FOSS and proprietary), strong interest in coding, native English speaker, familiarity with nerdy pop culture, the right hardware (Thinkpad).
Even then I had to get over a major hump in order for me to make my first contributions.
Some of this might have been easier if I had more experience with software development and Linux. However, I put off learning Linux for over 5 years because I never had a real reason to use it! Working in FOSS was my driving impetus to learn software development and Linux. So that is the "chicken and egg" problem, at least for me personally.
Working on OpenStack
At the end of the application period, I picked OpenStack as my first choice organization.6 Happily, I was selected, and shortly afterwards, began working on OpenStack.
It's true that I made my first FOSS contributions while applying to Outreach Program for Women, but those were simple patches like fixing typos and adding documentation. Being an OpenStack intern provided me with my first experience in working on substantial patches that needed to work with a large codebase and that required significant code review.
I found out later that OpenStack is not an easy project for newcomers to get into. Recently, while I was on IRC, I had an interesting discussion with someone from India. The person told me that OpenStack has a "tough" reputation. They tried to install Devstack unsuccessfully, and their friends had the same experience.
I was lucky to have the help of Anita Kuno, a recent OpenStack intern alumnae, who put heroic, generous effort into getting me started. She showed me how to install Devstack step-by-step and how to use Gerrit. When needed, she talked to OpenStack people on my behalf. After my very first contribution to OpenStack's Gerrit system, I had a strange, private interaction on IRC with someone who saw my patch. I told Anita about it, and she dealt with the person immediately.
Here at OpenStack, I have my team of supporters. Besides Anita, I have Julien Danjou (my mentor), Julie Pichon (former Outreach Program for Women mentor), and Anne Gentle (OpenStack's Outreach Program for Women coordinator) as well as past OpenStack interns Victoria Martínez de la Cruz and Laura Alves.
It goes without saying that having a good mentor is essential. I'm always able to get in touch with Julien, no matter how busy he is as Ceilometer Project Technical Lead. During the Outreach Program for Women application process, I interacted with some mentors who seemed "too busy" and found it frustrating, so I truly appreciate Julien's effort to be available. It's also very helpful to have the "team" of supporters I just mentioned. When someone is busy, I can try someone else.7 All the people on my "team" work on different things and have varied backgrounds, which means they have different perspectives. This is also extremely educational and useful for me.
Personally, I've found that good mentoring is not purely based on technical knowledge and experience. While those things are important (and essential to have in at least one mentor, in my case, Julien), I think good judgment and thoughtfulness are equally relevant. People who have less experience can mentor, too, if they are thoughtful. They can help out with the things they do know about and refer me to others when they feel like a matter is outside their domain of experience. It's very useful to have a "cultural ambassador" who can show you around the FOSS community and be a role model for how to behave.
I'm not saying that technical knowledge isn't necessary at all in mentoring; I'm merely trying to highlight some other factors which may not be as obvious.
Beyond mentoring, here are some things I experienced/learned while being a new contributor to OpenStack:
I wasn't sure how much or how little I could bother people on the development channels. Hypothetically, at what point would I bother people to look at my patch? (In reality, I've always gotten prompt reviews.)
I work on OpenStack in a virtual machine,8 which gives me peace of mind. If the development environment becomes irreversibly screwed up, I can always trash my current virtual machine and start a fresh one. Then after installing Devstack, I can resume work on my current patch using the command
git review -d patch####.9 The point is that I shouldn't fear making mistakes in my local development environment, if it's on a virtual machine.
If people know I'm new to software development and the project, it's okay to submit an incremental patch. What I mean is that if I'm not sure what I'm doing and the patch can be naturally partitioned, I can submit the patch part by part. For example, if I'm working on a feature in multiple back-end drivers, I could divide the patch into 4 parts: 1) test for the drivers, 2-4) implementation for each of 3 drivers. People can comment as I submit each part, so that I know I'm on the right track.
I can mark patches on Gerrit as "drafts" or use the "work in progress" status if my patch is not ready for a major review.
It's important to know who to go to when there is a significant issue, especially if it's relevant to the entire community. If I have technical issue, I can go to my mentor Julien Danjou. If I have a non-technical issue, I can go to Anne Gentle (OpenStack intern coordinator) or one of the Outreach Program for Women coordinators, Marina Zhurakhinskaya and Karen Sandler. I hope everyone has someone they can go to, in their own FOSS community.
The one important thing I learned about contributing to open source
This might sound clichéd, but I think open source is very much about the people. You can learn a lot from internet tutorials, but there are always unforeseen obstacles and you need people to guide you through them.
Thanks to many many kind, supportive individuals I was able to
repair my Git history,
survive the Devstack gauntlet,
fend off weirdos,
and most importantly, feel welcome as a bona fide member of the open source community.
Thinkpads are among the best supported machines in the Linux world, and the secondary slot allowed me to install a second hard drive that I could run Linux on, without any risk to my primary hard drive with Windows on it. I also had my RAM maxed out to 8 GB, which was very helpful later on, when I ran Devstack in a virtual machine. ↩
I recently wrote a OpenStack-related post about how to install Devstack and Ceilometer. In the troubleshooting sections, I mention lots of bugs related to missing dependencies, all of which I encountered while trying to install software or run tests. ↩
I did go through a very short Git tutorial, but in my opinion, it wasn't sufficient. The application process put me under time pressure, so I wasn't able to do a more thorough tutorial. ↩
I speculate this is the reason that Google Summer of Code requires multiple mentors for each intern. Google Summer of Code is an FOSS internship program similar to Outreach Program for Women, but it focuses on coding and is restricted to students. ↩
This command automatically downloads the patch and creates a branch for the patch in your local Git repository. ↩
The image I used for this post is a screenshot of my very first OpenStack contribution. ↩