Last updated 18 December 2017.

A guide to good mentoring experiences

At Drupal events, the Mentored Core Sprint usually takes place in a large room with many round tables. You will mentor 3 to 8 people sitting at your table. This guide aims to help both new and experienced mentors have good experiences while mentoring. It is based on notes taken during mentoring orientation with Cathy Theys (YesCT) at DrupalCon Bogotá in 2015.

(Not) knowing all the things

Being a good mentor does not mean knowing all the things. It is impossible for one person to know (or do) all the things. As a mentor, it is OK for you to ask for help. Or say "I don't know".

Good mentors share what they know, how they know it, and are open about what they do not know.

New contributors are often afraid to make comments on issues, or change the status of an issue. They think that special permission is needed, or that they should only post a comment when they know all the things.

It is important for people who are sprinting to see that they do not have to know all the things. By seeing mentors say "I don't know... but the way I would find out is by doing..." is really empowering for new sprinters. They see others they respect do not know all the things, and they learn how to learn things by finding out things alongside their mentor.

Tell sprinters that it's OK to post comments and questions to issues, even if they have doubts.

The most important thing

A sprint is for people who know what Drupal is and have worked with it in some capacity. We need a lot of different kinds of people to participate and contribute in different ways, not just code. But the most important thing to remember, for both mentors and sprint participants, is to have fun.

Trying new things and trying to understand new things can be confusing and frustrating sometimes. Sprint participants may feel that they are under pressure to contribute something, anything. They may feel that they failed if they do not make what they think is a meaningful contribution.

It is important for both mentors and sprint participants to remember that contribution is a process. Drupal is made through lots of little tasks. We are all here to learn. So have fun, and try new things. Build on the knowledge that you have.

The most important outcome is that people will want to continue to contribute or sprint again.

Celebrate small successes like posting a comment with a question, posting a screenshot, or posting a broken patch. Talk to new sprinters and reflect with them on all they had to learn in order to do that, so that they recognize they have done something meaningful.

When new sprinters learn, have fun, and can see a result of their work (a comment on an issue), then they are more likely to continue contributing at home, or attend another sprint.

Hello, my name is…

emmamaria at DrupalCon Bogotá (photo by Jared Smith) Your day will begin with getting to know sprint participants. Introduce yourself and ask everyone their name. It is helpful to write down their names.

Name tags

At a sprint, we ask participants (and mentors) to put on name tags, even if they are already wearing their event badge. This is because when sitting down, the badge is often hidden below the table. And, some people forget to bring their event badge to the sprint.

Tell sprinters to say "hello" to you on IRC, using your IRC username. Try to connect the person to a name and their IRC/Drupal username. Have each person tell a fact about themselves, or where they are from to help you and everyone remember their names.

Get to know new sprinters

Ask everyone,

What do you do with Drupal?

This is an open question, which makes it less intimidating than "Do you know…?" or "Have you done… before?"

Ask new sprinters why they are attending the sprint and what they want to get out of attending the sprint. They may want to contribute to Drupal Core by doing something they are already skilled doing. OR, they might be at the sprint to learn something new while contributing at the same time.

With that information, you can help them find something relevant to work on and match them up with others at the sprint.

Also, with that information, you might want to talk with them about what reasonable expectations are for what they might accomplish at the sprint. When their expectations are reasonable, they will have a better experience.

Identifying mentors

It should also be easy for participants (and you) to spot other mentors, who can be asked to assist. At some events, mentors wear matching, bright color T-shirts. If there are no mentor T-shirts, we can use bright tape on dark color T-shirts, as we did in Bogotá.

Talk in the open

It important that you do not talk in private (private chat or away from the table). When you speak publicly, other people can learn from the conversation. And others overhearing the conversation can clarify or correct anything, so that you can learn, too. Open source your conversations!

Talking in public shows that asking questions is OK. Explain it is safer to say the wrong thing in public because there are people who will correct it.

If you do not know the answer to a question, talk out loud and show others how you find the answer. It is important not to know things because that is how you can show sprint participants how to learn things.

Tools that we use

DrupalCon Bogotá Sprint (photo by Amazee Labs) Drupal community uses IRC (Internet Relay Chat) to share information, especially links, during sprints. There is a general purpose #drupal channel. #drupal-contribute is where people working on issues talk to each other. There are also regional channels, channels for contributed modules, and other Drupal topics.

It is worthwhile to get familiar with the Development Environment page, which has recommendations for IRC clients, editors, Dreditor browser plugin, and other tools.

The Tools page explains how to use the automatic installer of Drupal development tools.

In case wifi is overloaded, we will also have USB keys with folders containing the tools Mac and Windows in separate folders. Sprint participants can copy the installers and tools for their OS from the USB keys. It is helpful to have a recent copy of the Drupal git repository already on your laptop.

Working in the issue queue


We want to make people want to work on Drupal. They should have a good time and not hate it. When they return home they should feel confident they can contribute and learn what they need to know.

As a mentor, give sprint participants doable tasks. Expose them to how we know the things that we know. For example, if a participant wants to know what kind of tasks they can do, you can ask in IRC: contributor tasks? and have drupalbot reply with the information and link.

We want sprint participants to have success with at least one aspect of contribution. The most basic goal for mentors is to make sure new sprinters do something and click Save.

Picking an issue

It will take a while to find an issue to work on. Selecting novice tasks for new contributors helps people decide what is a novice task and what is not.

Sprint participants are skilled at what they do. Tell them you know that, so that they are not offended when mentors encourage them to work on simpler novice contributor tasks. Explain that mentors recommend easy tasks so the participants can focus on learning the contribution process. For new sprinters, the code should be "easy" so that they can absorb all the new tools and techniques they are learning.

Pick an easy task, something that would take you 10 minutes, but for new contributors it might take an hour. Make sure that they complete that task and get a result. Check back in with them and ask them how it is going. Help them recognize easy wins.

Besides issues tagged novice, good issues are issues that you have worked on before and know about. Mentors can identify good novice tasks within issues that mentors have experience with, and mentors can review work on them more easily than issues that mentors are unfamiliar with.

Ask, "We can find an issue to work on together, would you like that?" Give expectations, "You will have to be patient." Find out what they're interested in, "Are you interested in anything in particular? Multilingual, front end markup, etc?"

Use Drupal 8 core advanced search to find issues. Ask the person to find Drupal 8 core advanced search.

Avoid handing out issues

The issue queue can be scary for new contributors. There is a lot of information to take in. But, try not to pick issues for them. Instead, show new contributors how to find an issue, so they can do the same when they go home.

To make it easier, we tag issues with the Novice tag.

Show new contributors how they can combine a topic tag with the Novice tag in the issue advanced search page by changing the exposed filter on tags to "is all of" to find more specific issues they want to work on.

Always post comments

Instead of using the Assigned field, ask the person to post a comment on the issue saying what they are about to do.

It is important to leave issues unassigned, rather than claiming them. When issues are assigned, sometimes a person stops working on the issue, but forgets to unassign it. When that happens, other people will avoid an issue in the future, and work on it stalls.

Assigning is also less useful as we have evolved over the years to recognize that several people can be working on an issue at the same time: one updating the issue summary, one drafting the change record, one reviewing code, one manually testing a patch, one writing a patch with tests... so assigning to one person is not as useful as a comment from each person saying what they are about to do.

Explain to sprint participants that talking through comments is very valuable. When multiple people comment on the same issue saying what they are about to do, locate other people who are already working on the issue, and put those people together.

Sometimes new contributors will be reluctant to make a comment. They may say "I will make a comment ... tomorrow" or "when I get this test working". But experience has taught mentors that when people say they will finish later and post a comment later, they are likely to not do it. Explain to new contributors the advantages of posting comments during the day, and one before they leave the sprint.

The advantages are,

  • they can locate others working on the same issue and work together,
  • they can get feedback early to make sure they are going down a good path,
  • it makes it easier later to understand the direction an issue went in, when the comments document the various things that were tried and discussed,
  • questions or half working patches are valuable in themselves,
  • their future self will thank their past self for making a comment

Tip: produce output early and often.

Show people that making a comment is a safe pattern. A new contributor may ask a mentor a question. Sometimes it is appropriate for a mentor to ask the new contributor to make a comment on the issue asking the question. Someone else who is following the issue might answer it. Or, the mentor can make a comment on the issue answering the question (and linking to how to know the answer).

The new contributor can also ask the question in IRC in #drupal-contribute (tell them to post a link to their comment on the issue where they also asked the question). Asking in IRC can increase the speed with which their question gets answered.

If the question is answered in real time either in IRC or in person, but the person answering does not also post the answer on the issue, encourage the new contributor to make a new comment on the issue, answering their own question. Tell new contributors that this is a common pattern that even experienced contributors will follow.

Issues to avoid

New contributors should avoid working criticals. Criticals may be OK to work on if the sprinter had success early in the day and if you can pair them up with an experienced contributor who is already working that critical.

Do not pick an issue that has had no activity on the issue for many months, because it is better to work on issues that people care about. At the same time, avoid hot, contentious issues that have a lot of comments. These issues may be hard to follow for a new contributor.

See more in the handbook page: Selecting novice tasks for new contributors.

Check in regularly

DrupalCon Amsterdam Sprint (photo by Boris Baldinger) Show people how to do a task by pointing them to documentation. For example, ask, contributor tasks? in IRC.

Show new contributors instructions for updating an issue summary (issue summary?). Give the person time to read and digest instructions.

Follow up on their progress by asking,

What are you working on?


How is it going?

rather than "Did you do (the thing I asked you to do)?" or "Are you done with…?"

"What are you working on?" is an open-ended question that creates an opening for the person to ask you questions or tell you that they are unsure about something. It is more respectful of the person's time and skills.

When reviewing progress, ensure that the participant is referencing and following the contributor task guidelines for the type of task they are working on.

Live commit

As the day goes on, keep a list of issues that are becoming RTBC (reviewed and tested by the community). Show the issues to another experienced mentor or the sprint lead. The lead is watching all these to pick one that is really RTBC. An issue may be RTBC and then needs work and then RTBC a few times.

With one of these a live commit may happen toward the end of the day.

This is an opportunity to bring together all the people who worked on an issue, have them be recognized in front of all the people at the whole sprint. They explain the issue, and talk about what they did.

The core committer will then discuss how they approach committing a patch. They will show everyone in the room how they read the patch, review it and commit it. Or, they might find that more work needs to be done and explain why.

Live commits are fun and exciting. Our goal as mentors is to help new contributors find issues that can reach RTBC status and work on them with others (one person can update the issue summary, another can re-roll a patch, while a third person can review it).

But it is important for sprint participants to understand that this should not be the only goal. They should aim to increase their knowledge, make whatever contribution they can, and have fun along the way.

Issue credit in Drupal Core

Introductions with regular contributors

Where a general sprint is taking pace nearby tot the mentored sprint, it works well, after the core commit, to ask those regular contributors in the general sprint room to come through to the mentored sprint room, find people that have been working on issues in their area of interest and introduce themselves. It is quite possible that the new contributors may be working with them in the future.

Note that it is less intimidating for the regular contributors to get up and go into the other room rather than the other way around.