-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathtools.tex
104 lines (72 loc) · 14.7 KB
/
tools.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
\chapter{Tools}
“It's supposed to be automatic, but actually you have to push this button.” - John Brunner, Stand on Zanzibar\todo{make this a proper quote}
There are a lot of useful tools out there to help you do outreach. Let’s look at a few of them in this chapter.
\section{Start with the basics}
We hope your project already uses some basic tools that help people show up and participate:
\begin{itemize}
\item Mailing lists with public archives
\item A bug tracker that new contributors can use without asking for permission
\item A website that succinctly describes what your project is
\item Perhaps an IRC channel for real-time questions
\end{itemize}
You can read more about those in Karl Fogel’s Producing Open Source Software\footnote{\url{http://producingoss.com}}.
While the basic tools are all important, make sure to not spread yourself too thin. Do not overwhelm people with too many choices. It is much better to have a single email address or channel you check regularly than several avenues for contact that no one actually looks at. You should assemble information and links to all the resources, opportunities and events that are available to newcomers on a single GettingStarted page for your project. Try to get an overview of how new people see your project by having an unconnected friend try to figure out how to do simple tasks like filing a bug or asking a question.
\section{Informal mentorship}
\subsection{What it is}
One way to get new people into your project is to explicitly offer mentoring throughout the year. This can happen informally and have no or little structure. The key is to connect newcomers with a mentor from the project that they can come to for help when they have problems and who introduces them to the community and its way of doing things.\todo{shorten sentence} Newcomers can choose a mentor from a mentors list to contact directly, be introduced by a coordinator or be matched up with a mentor who responds to their request on a mailing list.
For a newcomer, not knowing anyone personally is one of the biggest obstacles to beginning to contribute, and informal mentorship immediately provides a connection with a friendly person in the project. Additionally, a mentor is in a good position to direct the newcomer to relevant tasks, which are often hard for a newcomer to identify.
\subsection{What you need for it}
You need mentors who are patient and understand the problems someone has when they are new to your project. You need to create a list of such mentors, their contact information, and areas of expertise and include it among your getting started resources. Alternatively, you can create a mailing list where newcomers can send their questions and requests for mentors. In that case, you still need to have people who respond to the requests on the list.
\subsection{Where it works}
A lot of projects do it but some are more successful than others. Taking some time to make sure that both mentors and mentees have reasonable and matching expectations can help you avoid a lot of problems. Regular check-ins between mentors and mentees are essential for successful mentoring. Successful projects also make a point of having mentees become mentors after a while.
\subsection{What to watch out for}
Make sure the people who are mentoring are actually good mentors. Mentoring well takes a set of skills that not everyone has developed. Also watch out for mentees who are not starting to work on their own after some time and are just draining your mentor’s time and motivation.
\subsection{In more depth}
A list of projects and their ad hoc mentor lists can be found on the GSoC wiki\footnote{\url{https://code.google.com/p/google-summer-of-code/wiki/Mentors}}. Take a look at the different ways the informal mentorship is provided in other projects and add your own project’s mentor list!
\section{Formal internships}
\subsection{What it is}
In formal internships people, usually students, apply to do an internship at a free software project. The selected participants then work on a specific task or area of the project that was agreed upon. They get one or several mentors to guide them and introduce them to the project. These internships have a limited duration of usually three months. After that the participant is expected to be well acquainted with the community, the software and everything else they need to be a successful member of the project. There are different reasons for people to take on such an internship. The reasons can include a combination of wanting to become an established project contributor, improving skills and learning new ones, earning money, and satisfying an internship requirement at college. Whatever their motivation is, be aware of it and do not expect all participants to stay with your project. You can be sure however that the internship and exposure to free software values will have a profound impact on their career and life.
\subsection{What you need for it}
You need some kind of legal entity and a person who can take care of contracts and payments. Additionally, you need a person who manages the internship program and makes sure mentors and interns have someone they can go to in case of problems. This person should also do regular check-ins with everyone involved.
Providing internship opportunities helps attract new contributors to the project. For new contributors, it is highly advisable to have a pre-qualifying task in which they would show their motivation, skills and ability to work with others by downloading and building the code for the project, making changes to it, and using the appropriate communication channels for accomplishing the task.\todo{shorten sentence} The task can either be a simple bug or a prepared assignment. Informal help from the project’s mentors should be available to the applicants during that time.
It is important to define the internship project well, leaving some flexibility to adjust the tasks throughout the internship. Incorporating the participant’s work into the project is a very important goal, and for that, the project should consist of manageable and relevant tasks that would allow the intern to feel the satisfaction of landing their work throughout the internship. Avoid having interns work on features that do not have consensus about them, have too many moving parts or are a stand-alone project that could only land in the main branch in the end of the internship period as a best-case scenario. Connect applicants with prospective mentors during the application process for them to define the internship tasks together.
Depending on your project it might be advisable to do a collaborative application process during which the applicant and the mentor work together on an initial required contribution and a project plan. This can provide information that serves as a great selection criteria, prepare accepted interns for their work, provide all applicants with an experience of contributing to free software and tie to the project.
You should make an effort to integrate the interns with the rest of the community during the internship period. Requiring interns to blog about their progress and aggregating their blogs on your project’s planet, IRC meetings for interns and helping the interns come to relevant conferences and hackfests are some of the ways this can be accomplished.
\subsection{Where it works}
Google Summer of Code and the FOSS Outreach Program for Women are two well-known programs that do successful internships across a number of projects and any free software project can consider joining one or both of them. If you have a big organization and the necessary resources, you can also organize your own internships. It is important that the mentors in your community are able to dedicate several solid hours per week to guiding the interns they are mentoring during the course of the internship.
\subsection{What to watch out for}
You need to be aware that internships require a considerable investment of time and money from your side. Some applicants may squander this investment. Do your best to try to spot them during the selection process. Some applicants have trouble delivering the work they promised. Plan accordingly and lay out reasonable milestones together with them. Since money is involved, unfortunately some applicants might try to cheat. And last but not least, you might have mentors who are not actually good mentors. Make sure you spot them early and replace them with a better mentor as soon as you can. If that is not possible, try to put a second mentor on the team.
\subsection{Further reading}\todo{make this a list and add links}
The DOs and DON’Ts of Google Summer of Code: Student Edition
The DOs and DON’Ts of Google Summer of Code: Mentor Edition
The DOs and DON’Ts of Google Summer of Code: Organization Administrator Edition
\section{Step-by-step tutorials}
\subsection{What it is}
You can create tutorials for new contributors that are action-based, have clear steps, and provide straightforward assessment (either automated or self-assessment). The key is providing well structured information relevant to contributing to your project so that newcomers can learn the basics without taking up your time and without feeling embarrassed about not knowing something.
\subsection{What you need for it}
The skills required to contribute to your project have to be skills that you can find good tutorials for. Take a look at the OpenHatch training missions\footnote{\url{https://openhatch.org/missions}} to see if there is one that fits your project (for example, diff/patch, tar, git, svn). Review GNOME’s Newcomer tutorial\footnote{\url{https://live.gnome.org/NewcomersTutorial}} for a longer example that goes through the full, GNOME-specific workflow of downloading a module, running its code, making changes and creating a bug with a patch in Bugzilla. GNOME’s tutorial relies on a placeholder Bugzilla product that newcomers file their bugs against. For a smaller example, consider this tutorial on adding a feature to GIMP\footnote{\url{http://www.ibm.com/developerworks/linux/library/os-gimp}}. Take inspiration from these tutorials and consider creating your own if needed.
\subsection{Where it works}\todo{this isn't really ``where it works''}
The perceived extent of knowledge all existing project contributors have can be intimidating to a newcomer and discourage them from even trying to get up to speed with the project. The tutorials should give the newcomer the information that will allow them to begin
making meaningful contributions and building up confidence as a contributor. Of course the
tutorials cannot cover all the code, so soon the newcomers will need to dig deeper.
\subsection{What to watch out for}
Existing missions and tutorials might not cover your workflow, so do try them first and use them as an inspiration for other tutorials you might write. You can send patches to extend the existing OpenHatch training missions.
\section{Bite-sized bugs}
\subsection{What it is}
Getting into a new project can be overwhelming and a lot of people give up if their first task is too hard. Therefore one of the easiest things you can do for your project is to make a list of small tasks that a newcomer can work on. You should have this list ready whenever someone comes to join your project. They are right then and there ready and willing to put time and effort into your project. You should be prepared because this initial enthusiasm might otherwise not last.
\subsection{What you need for it}
A list of small bugs or tasks in your project that someone who is not already familiar with your project can solve. Make sure to also include non-coding ones. Each bug should state what skills are needed in order to fix it and, ideally, what parts of the project the bug will help a new contributor become familiar with.
\subsection{Where it works}
Everywhere! Some of the projects successfully publishing such tasks are KDE (junior jobs), GNOME (GNOME Love), and LibreOffice (easy hacks). KDE and GNOME use a tag on their bug tracker to mark these tasks; LibreOffice goes one step further and maintains a wiki page\footnote{\url{https://wiki.documentfoundation.org/Development/Easy_Hacks}} that contains a brief summary of a hand-picked assortment of easy tasks, including what skills are required to address it.
\subsection{What to watch out for}
Keep the list up-to-date and make sure it includes meaningful tasks. No-one wants to work on things that are not useful and just waste their time. Make a point of giving timely feedback to questions and patches.
\section{Newcomer inclusion contests (e.g. Design Bounties)}
\subsection{What it is}
Newcomer inclusion contests (most famously, Fedora Design Bounties) are a process where you find and document one task that a newcomer could address. The newcomer who claims and finishes the task gets a prize that encourages further involvement. For example, commit access or a title that represents status in the community are great rewards. By offering the opportunity to participate more, these contests select for people who are interested in contributing for the long term.
\subsection{What you need for it}
You need to be able to write effusively about how great it will be if someone solves the task you have chosen! You should also explain how the first task will lead to other more important tasks. The task you choose should be meaningful, but understandable for a new person to take on. You will need to identify which project resources a newcomer would need to know about and provide a very clear link to relevant documentation. Your fellow contributors should carefully refrain from working on it during the contest period. Make sure your newcomer won’t have the rug pulled out from under them.
The post about the contest works best on a personal blog or other resource where visitors can easily leave comments. It is also best if the post does not have distracting links to other project resources, allowing the visitor to focus on the contest. A prospective solver should be able to “lock” the contest for them to try to solve, for example for a 48-hour period, without having to jump through a bug tracker registration.
\subsection{Where it works}
The Fedora Design community, Students for Free Culture’s sysadmin team and the OpenHatch web development community have used this to great success. This outreach effort works best for communities with a high number of lurkers.
\subsection{What to watch out for}
Make sure to write a truly inclusive and easy-to-read blog post! The Fedora Design Bounty effort, spearheaded by Máirín Duffy, is a great collection of examples\footnote{\url{http://mairin.wordpress.com/category/fedora/fedora-design-bounty}}. And make sure you can find a place to get readers. If your community does not have the visibility necessary, it could help to cross-post it onto other technical forums.