Latest revision as of 20:47, 13 September 2014

Short link to this page: bit.ly/finding-a-project

So you want to contribute to an open source project. With tens of thousands of options to choose from, how do you find one that's right for you? This activity is meant to help you narrow down your options to a few different projects you can pursue.

To get ready, all you need to do is take out a piece of paper, open up a text editor, or start an etherpad, for taking notes as you follow these steps. An easy way to take notes could be to use the template we've provided in this etherpad - you can copy and paste that text into your text editor and then fill out answers as you go along. (If that's accidentally been edited, try here.)

Optional: find a friend or groups of friend to go through the activity with. They can help with each step. Maybe you'll even pick a project to contribute to together!

Step 1: Brainstorming Projects

Read through the following questions and think about what projects your answers suggest. Write those projects down on the etherpad:

What open source software do you use? For instance, if you use Firefox, are you interested in helping improve it? You can also consider related projects, in this case Firefox add-ons, or programs/libraries that Firefox uses to function. If you're not sure which of the software you use is open source, make a list of what you use and do a search to find out if they're open source.

Is there a project whose goals you find compelling? For instance, you might want to look at humanitarian projects like Sahana, or projects relating to a hobby of yours like music, videogames, or reading. If you're studying science or engineering, you might look for projects that are used by people in your field.

Are there any people you know who work on open source projects? Professors, classmates, friends? Getting to work with someone you like is a great reason to join a project!

You can also search through lists of projects and write down any projects that catch your eye. Here are some resources that list open source projects:

Curated lists (more useful):
- Google Summer of Code mentoring projects

Large lists/databases (less useful):

Step 2: Researching Projects

Once you've got at least 1 project on your list, it's time to start researching. (It's great to have more than 1 -- you might find that the first project you pick isn't a good fit for you.) For each of them, you need key information, including:

website url
source repository url
mailing list
IRC channel
contributor guide
installation guide

Write this information down as well. Every project will not have every item, but you should look for all of them. Sometimes the url will be the same for multiple items - for instance, the contributor guide and installation guide may be part of the same document. You can write down any other relevant information or links you find as well. (If you want an example, look at the template Etherpad document, but a bulleted list is fine.)

Some advice: The simplest way to find the project's main website is to google it. A well maintained project will have links from the website to their source code repository, issue tracker, mailing lists and IRC channel. Sometimes this information will all be bundled together in a “developer guide”. Larger projects may have multiple mailing lists for different people (developers, users, translators, etc) and for different parts of the project. Some code hosting services, such as Github, provide issue trackers as well. You can usually find a link to the issue tracker in the code repository and vice versa. Popular services include Github, Google Code, Bitbucket, SourceForge and Gitorious. Popular issue tracker services include Bugzilla, Github, and Google Code.

Step 3: Evaluating Projects

For each of your potential projects, you'll use the information you gathered in the last step to help you evaluate the project. You can evaluate the project by asking yourself the following questions. Write down your answers!

Is this project active?

Take a look at the issue tracker. When was the last issue reported? Or take a look in the source repository and see - when was the last commit? If the answer is "today" or even "this week", that's great! Your project is definitely active. If it's been a few months, that may mean that the project is abandoned, or it may mean that it's been quiet for a while. Even if the project is still going, the maintainers may want to focus on other things for a while. If the answer is "years", the project is probably abandoned. If the project has had commits made or issues reported within the last few months, take a look at the rate: how often do issues get reported or commits get made? Once a day? Twice a week? Once a month?

How responsive are the maintainers?

Take a look at individual issues. How long does it take a maintainer to respond - if ever? Or look at pull requests, for instance on Github. Are there dozens of pull requests languishing for weeks or months? That may mean that the project's maintainer is overwhelmed or busy or just not very responsive. Look for pull requests that have a back and forth between the maintainer and the requester. Is the maintainer giving feedback and helping people submit appropriate requests? If so, that's a very good sign!

Is the community welcoming?

Every project is made up of individuals, and this means that each project has a different atmosphere or culture. You can read through their mailing list archives, or lurk on their IRC channel (or read their channel logs, if available) to see how newcomers are treated. When people have questions, are they answered patiently or ignored? Are the community members friendly with each other, and talk about things other than the project? If that's a dynamic you like, you can search for it. One thing to look for are codes of conduct. A lot of smaller projects don't think to have them, but many larger projects do, and you can get a sense of the kind of community a project has by seeing what kind of behavior they tolerate and what they discourage.

Is the project the right size for me?

Projects vary greatly in the size of the community and in the size of the project itself. Ask yourself what size project you are looking for. Each has its advantages. For instance, a larger project will likely have more and better documentation, while a smaller project will have fewer elements to learn about. A larger project may have more people who can help you, but it may be easier to get lost in the crowd.

Step 4: Contacting Projects

From the above steps, you should hopefully have found at least one project you think you'd like to contribute to. That's great. For at least one project, take at least one of the following steps. We highly recommend at least saying hello in IRC.

Say hello on the IRC channel

If the project has an IRC channel, join it and say hello to the community members. If there's anyone around, you can tell them you're new to the community and interested in contributing.

Here are some questions you can ask the people in the channel:

What do they like about the project? How long have they been involved with it?
If you have an issue you'd like to work on (see below): is anyone familiar with the issue? Otherwise: Are there any issues that people are especially keen to see being worked on?
Is there anything particularly complicated or difficult that might be an obstacle to contributing? How would they suggest dealing with that?
What do people like to do when they're not contributing to the channel's project?

Say hello on the mailing list

Before saying hello on the mailing list, take a look through the archives and see if "introductory emails" are a thing. If they are: great! Say hello. If not, see if there's a contact person (or list of people) for the project (for instance, OpenHatch has hello@openhatch.org). You can send them an introdutory email instead.

Find an issue you might want to tackle

Read through the project's issue tracker and try to find an issue that seems interesting to you. Many issue trackers will have tags, categories, or text searches that can help you filter issues, or you can just browse. Some projects will tag issues as "beginner", "small", "easy" or "bitesize" -- those are great issues to begin with! If you find an issue you'd like to work on, leave a comment on the thread saying you'd like to do so.

Remember, when looking at issues, make sure they haven't already been solved/closed. Also, check and see if it's assigned to somebody else. If it is, but that person hasn't done anything with it, you can comment asking if they would mind if you tried to address the issue.

You can also leave a comment reproducing a bug. If you do that, make sure to include relevant information about the version of the project you're using, the system you're on, and other potential factors.

Going Forward

That's it! You're done with the activity.

A quick note: you might wonder why we asked you to find multiple projects. The truth is that finding a good open source project is a lot like dating or finding a job. It often doesn't work out on the first try. That doesn't mean you're a bad contributor or that the project is a bad project - it may just be a bad fit, or bad timing. So keep an open mind, and keep trying projects until you find one that you really enjoy contributing to.

One more thing: we'd love to see your worksheet for this activity! We want to see how people are using it so we can improve it. You can send it to us (anonymously or not) at hello@openhatch.org.

@@ Line 1: / Line 1: @@
+= Short link to this page: '''bit.ly/finding-a-project''' =
 So you want to contribute to an open source project.  With tens of thousands of options to choose from, how do you find one that's right for you?  This activity is meant to help you narrow down your options to a few different projects you can pursue.
-To get ready, all you need to do is take out a piece of paper, open up a text editor, or start an etherpad.  You can use the template we've made in [https://etherpad.mozilla.org/finding-a-project this etherpad].
+To get ready, all you need to do is take out a piece of paper, open up a text editor, or start an etherpad, for taking notes as you follow these steps.  An easy way to take notes could be to use the template we've provided in [https://etherpad.mozilla.org/finding-a-project this etherpad] - you can copy and paste that text into your text editor and then fill out answers as you go along.  (If that's accidentally been edited, try [https://etherpad.mozilla.org/ep/pad/view/finding-a-project/rev.659 here].)
 Optional: find a friend or groups of friend to go through the activity with.  They can help with each step.  Maybe you'll even pick a project to contribute to together!
@@ Line 18: / Line 20: @@
 * Curated lists (more useful):
-** OpenHatch's recommended projects page
 ** [https://www.google-melange.com/gsoc/org/list/public/google/gsoc2014 Google Summer of Code mentoring projects]
@@ Line 28: / Line 29: @@
 ** [https://github.com/explore explore github]
-== Researching Projects ==
+== Step 2: Researching Projects ==
-== Evaluating Projects ==
-== Contacting Projects ==
+Once you've got at least 1 project on your list, it's time to start researching. (It's great to have more than 1 -- you might find that the first project you pick isn't a good fit for you.) For each of them, you need key information, including:
+* website url
+* source repository url
+* mailing list
+* IRC channel
+* contributor guide
+* installation guide
+Write this information down as well. Every project will not have every item, but you should look for all of them.  Sometimes the url will be the same for multiple items - for instance, the contributor guide and installation guide may be part of the same document.  You can write down any other relevant information or links you find as well. (If you want an example, look at the template Etherpad document, but a bulleted list is fine.)
-What open source software do you use?  For instance, if you use Firefox, are you interested in helping improve it?  You can also consider related projects, in this case Firefox add-ons, or programs/libraries that Firefox uses to function.
+Some advice: The simplest way to find the project's main website is to google it.  A well maintained project will have links from the website to their source code repository, issue tracker, mailing lists and IRC channel.  Sometimes this information will all be bundled together in a “developer guide”.  Larger projects may have multiple mailing lists for different people (developers, users, translators, etc) and for different parts of the project. Some code hosting services, such as Github, provide issue trackers as well.  You can usually find a link to the issue tracker in the code repository and vice versa.  Popular services include Github, Google Code, Bitbucket, SourceForge and Gitorious.  Popular issue tracker services include Bugzilla, Github, and Google Code.
-Is there a project whose goals you find compelling?  For instance, you might want to look at humanitarian projects like Sahana, or projects relating to a hobby of yours like music, videogames, or reading.  If you're studying science or engineering, you might look for projects that are used by people in your field.
+== Step 3: Evaluating Projects ==
-Are there any people you know who work on open source projects?  Professors, classmates, friends?  Getting to work with someone you like is a great reason to join a project!
+For each of your potential projects, you'll use the information you gathered in the last step to help you evaluate the project.  You can evaluate the project by asking yourself the following questions.  Write down your answers!
-To find projects related to some topic, you can google “[topic] open source” or “[topic] free software” and see what turns up.  You can also try the links listed here: https://openhatch.org/wiki/Project_sources
+=== Is this project active? ===
+Take a look at the issue tracker.  When was the last issue reported? Or take a look in the source repository and see - when was the last commit?  If the answer is "today" or even "this week", that's great!  Your project is definitely active.  If it's been a few months, that may mean that the project is abandoned, or it may mean that it's been quiet for a while.  Even if the project is still going, the maintainers may want to focus on other things for a while.  If the answer is "years", the project is probably abandoned.  If the project has had commits made or issues reported within the last few months, take a look at the rate: how often do issues get reported or commits get made?  Once a day?  Twice a week?  Once a month?
-Finding the project & its tools
+=== How responsive are the maintainers? ===
-The simplest way to find the project's main website is to google it.  A well maintained project will have links from the website to their source code repository, issue tracker, mailing lists and IRC channel.  Sometimes this information will all be bundled together in a “developer guide”.  Larger projects may have multiple mailing lists for different people (developers, users, translators, etc) and for different parts of the project.
+Take a look at individual issues.  How long does it take a maintainer to respond - if ever?  Or look at pull requests, for instance on Github.  Are there dozens of pull requests languishing for weeks or months?  That may mean that the project's maintainer is overwhelmed or busy or just not very responsive.  Look for pull requests that have a back and forth between the maintainer and the requester.  Is the maintainer giving feedback and helping people submit appropriate requests?  If so, that's a very good sign!
-Some code hosting services, such as Github, provide issue trackers as well.  You can usually find a link to the issue tracker in the code repository and vice versa.  Popular services include Github, Google Code, Bitbucket, SourceForge and Gitorious.  Popular issue tracker services include Bugzilla, Github, and Google Code.
+=== Is the community welcoming? ===
-Evaluating the project
+Every project is made up of individuals, and this means that each project has a different atmosphere or culture.  You can read through their mailing list archives, or lurk on their IRC channel (or read their channel logs, if available) to see how newcomers are treated.  When people have questions, are they answered patiently or ignored?  Are the community members friendly with each other, and talk about things other than the project?  If that's a dynamic you like, you can search for it.  One thing to look for are codes of conduct.  A lot of smaller projects don't think to have them, but many larger projects do, and you can get a sense of the kind of community a project has by seeing what kind of behavior they tolerate and what they discourage.
-Is the community active?
+=== Is the project the right size for me? ===
-When was the last commit?  When was the last bug report?  When was the last mailing list post?  Is there anyone in the IRC channel?  When was the project website last updated?
+Projects vary greatly in the size of the community and in the size of the project itself.  Ask yourself what size project you are looking for.  Each has its advantages.  For instance, a larger project will likely have more and better documentation, while a smaller project will have fewer elements to learn about.  A larger project may have more people who can help you, but it may be easier to get lost in the crowd.
-Is the community welcoming?
+== Step 4: Contacting Projects ==
-How do they treat contributors?  Read through their mailing list – are new contributors welcomed and supported?  Look through the bug tracker – do non-maintainers submit patches, and do maintainers work with them to get patches into acceptable form?
+From the above steps, you should hopefully have found at least one project you think you'd like to contribute to.  That's great.  For at least one project, take at least one of the following steps.  We highly recommend at least saying hello in IRC.
-To what extent do they care about users?  Does their project explain clearly what it does?  Is there good help documentation and/or FAQ?  Do they have large user group communities?  A community that treats users well is more likely to treat new contributors well.
+=== Say hello on the IRC channel ===
-Is the project used by its target audience?
+If the project has an IRC channel, join it and say hello to the community members.  If there's anyone around, you can tell them you're new to the community and interested in contributing.
-You probably want to work on a project that provides value to people, whether that's a small, niche group or a user base of hundreds of thousands.  To figure out if a project is actually providing utility, you can ask: is it packaged in Debian, Homebrew, Ubuntu or Fedora?  If so, it means at least one person on the project cares about getting the software to users.  You can also look for “use case” or “testimonials” on the project website to see how the project has been used.  For scientific projects, you can ask people in the field or see if the software is cited in articles.
+Here are some questions you can ask the people in the channel:
+* What do they like about the project?  How long have they been involved with it?
+* If you have an issue you'd like to work on (see [[Open_Source_Comes_to_Campus/Curriculum/Finding_a_Project#Find_an_issue_you_might_want_to_tackle | below]]): is anyone familiar with the issue?  Otherwise: Are there any issues that people are especially keen to see being worked on?
+* Is there anything particularly complicated or difficult that might be an obstacle to contributing?  How would they suggest dealing with that?
+* What do people like to do when they're not contributing to the channel's project?
+=== Say hello on the mailing list ===
+Before saying hello on the mailing list, take a look through the archives and see if "introductory emails" are a thing. If they are: great! Say hello. If not, see if there's a contact person (or list of people) for the project (for instance, OpenHatch has hello@openhatch.org).  You can send them an introdutory email instead.
-Activity: Find a project for your partner
+=== Find an issue you might want to tackle ===
-)  Spend a few minutes thinking about yourself and what kind of projects you'd like. At the end of those minutes, share what you've figured out with your partner., and they'll share what they've figured out with you.  You can write some keywords about their interests here:
+Read through the project's issue tracker and try to find an issue that seems interesting to you.  Many issue trackers will have tags, categories, or text searches that can help you filter issues, or you can just browse.  Some projects will tag issues as "beginner", "small", "easy" or "bitesize" -- those are great issues to begin with!  If you find an issue you'd like to work on, leave a comment on the thread saying you'd like to do so.
-)  Find 3 projects using the strategies outlined above.  For each, find the source code repository, the main developer mailing list, the IRC channel, and their issue tracker:
+Remember, when looking at issues, make sure they haven't already been solved/closed.  Also, check and see if it's assigned to somebody else.  If it is, but that person hasn't done anything with it, you can comment asking if they would mind if you tried to address the issue.
-Project Name
-Source Code
-Mailing List
-IRC Channel
-Issue Tracker
+You can also leave a comment reproducing a bug.  If you do that, make sure to include relevant information about the version of the project you're using, the system you're on, and other potential factors.
+== Going Forward ==
-For each of the 3 projects, evaluate if the project is active, welcoming, and used?
+That's it!  You're done with the activity.
-Project Name
-Is it active?
-Is it welcoming?
-Is it used?
+A quick note: you might wonder why we asked you to find multiple projects.  The truth is that finding a good open source project is a lot like dating or finding a job.  It often doesn't work out on the first try.  That doesn't mean you're a bad contributor or that the project is a bad project - it may just be a bad fit, or bad timing.  So keep an open mind, and keep trying projects until you find one that you really enjoy contributing to.
+One more thing: we'd love to see your worksheet for this activity!  We want to see how people are using it so we can improve it.  You can send it to us (anonymously or not) at hello@openhatch.org.
-BONUS:  For each project, try to find out the story behind why it was started, and/or why contributors are getting involved today.