| layout | title |
|---|---|
default |
Mentoring Program Guide |
This is the page to help people, who got accepted in a Mentoring Program like the Google Summer of Code (GSoC) or Outreachy, during the program. It can also help those interested in applying to such a program get an idea about how it goes.
First congratulations for being accepted!
The way you will be mentored depends on a lot of different things, for example how well you are doing, who are your mentors, what your project is about, what the mentoring program (GSoC or Outreachy) requires or suggests (which can significantly change each year), how the mailing list responds to your patches, what currently happens in your country or in your mentors' countries, etc.
This document might give you an idea about how things usually go, but don't be surprised if your mentors ask for things that are a bit different than what is described here. It's also possible that things change during the mentoring program. Typically your mentors will expect that you become more autonomous.
One of the first things you might want to setup (if you haven't one already), after you have been accepted, but before the working period actually starts, (GSoC calls this the "Community Bonding" period,) is a blog.
You might want to check which blogging tools previous Outreachy interns and GSoC students used. Using a Git related tools is of course a good idea.
For example using GitLab and GitLab pages:
https://mirucam.gitlab.io/outreachy_blog/ https://matheustavares.gitlab.io/ https://gitlab.com/MatheusTavares/matheustavares.gitlab.io/
Using GitHub:
If you already have something setup using other tools though, even if it's not Git based, it's perfectly OK to use what you already have, and focus on your project right away.
Your blog should be a tool to improve communication between you and the Git community, including your mentors. Your blog is also something that can help you in your career by reflecting positively on your abilities and dedication. A good example is Matheus' GSoC blog posts:
https://matheustavares.gitlab.io/gsoc
Mentors should be regularly updated about your work, so they can know if you are stuck on something, what you have done, and what you are planning to work on and how.
The best way to update everyone about your work is probably to post on your blog. We understand though that you might not want to put everything you might want to say on your blog. Also people on the Git mailing list might be interested to know that you published something on your blog, so that they can give you some help or feedback about your next steps or problems you are facing. Your mentors should be notified too that you posted something.
So we think that you might want to email the mailing list to notify every one about each new blog post. If you don't feel like doing that, we might find an alternative solution, but letting people know is often a good idea to get help and suggestions. You can also take advantage of the notification email to ask for help or to ask questions related to issues you have.
To notify your mentors, you can either cc them when you email the mailing list, or you can send them a separate email. In a separate email you might add things that you might not want to post on your blog or to the mailing list.
We require you to update your mentors at least every week. So the best is if you can post on your blog weekly (and send the related notifications discussed above). If sometimes for some reason (like a vacation or exams or family issues) you cannot post a weekly update, then it's OK to just email your mentors, or to ask them to have a chat one way or another. Then please make sure you post on your blog the following week.
In the blog post update and your emails to your mentors and the mailing list, it is important that you cover all the following topics:
- what you have done since last update and how
- what is blocking you if anything
- what you find difficult to do or understand
- what things you think should be easier
- what you are planning to work on and how
The reason we ask for 2), 3) and 4) is that often interns or students don't know about things, like existing documentation, historical discussions, debugging scripts, features, tools or techniques, that could help them understand what's going on, or work in a more efficient way. If a mentor doesn't know that the intern or student is blocked or slowed by something or has a hard time moving forward, it's difficult for the mentor to help. So it's important for interns or students to reflect on the issues, blocks, inefficiencies, complex things that they are facing.
Notifying the mailing list or your mentors about a blog post, should not prevent you from emailing or contacting the mailing list or your mentor when you might want to do that at other times. In general don't be afraid of posting or contacting people early and often.
It can help to sometimes have a chat (by that we mean a real-time conversation) with your mentors. This can especially help you when you are stuck or after you have reflected a bit on the status of your work and internship, and have doubts or feelings that things aren't going as well as they could.
As we think it's best that you decide on your own the best time to update your blog and send notifications, you should then also decide when it's best to have a chat with your mentors. So, unless you prefer to plan regular chats, your mentors might not ask for a chat, and might just want you to pro-actively email them when you want a chat.
Some mentors might not be always online on a chat platform, so you might need to schedule chat discussions, and try to find a good time for everyone. You can also propose the tools and media that work best for you (instant messaging, phone call, video call, WhatsApp, Zoom, or even email ...) and your mentors will likely do their best to adapt to your preferences.
Mentors usually look at their emails several times per day on week days, so you can say for example in an email that you are free during the next 2 hours to have a chat, and that could be enough to schedule a chat to unblock you. You can also use a notification email after a blog post to schedule a chat. In general if you are not blocked and you have more than one mentor, it's better to schedule a chat a few days in advance to increase the chances that all your mentors can participate.
In general for everything specifically related to your project and internship, it's better to try to involve all of your mentors (for example by Ccing all of them in emails, and by using an instant messaging group they all belong to), though we know it's not always possible or practical when you are blocked.
It could be OK to discuss personal or technical things or anything not directly related to your project with only one of your mentors, (like with anyone else). Just ask them.
If you prefer to have a completely fixed schedule from the start as you know each week well in advance when you will post on your blog and when you want to have a chat with your mentors, that can work too and you can probably set this up with them.
It's also OK to have such conversations completely over email if you prefer. We know that email is not usually considered really real-time, but we think it is, or can be, close enough compared to instant messaging chat for example. It sometimes happen on the Git mailing list that people debug together or discuss together something over email in a very real-time way (at least similar as instant messaging chat).
Such chats can sometimes help a student or intern (or even long timers on the project) move very fast in a short amount of time. So consider taking advantage of that.
It's also easier for mentors to help (or understand how they could help) when discussing informally using a real time or near real time communication medium, rather than blog posts or emails, so don't hesitate to ask for that even if you are not sure that they could help. And don't hesitate to ask them to use a medium you haven't already used with them, like Zoom for example to have a video chat, as sometimes it's just easier to understand something by sharing a screen.
You are also encouraged to take advantage of the whole Git community and its communication channels (https://git-scm.com/community), like the #git-devel IRC channel. Some or all of your mentors might not be on this channel or on alternative community channels you might want to use, but if you want to discuss with your mentors there, that's something they can consider.
Some mentors cannot easily let you know in advance what days and times they will be available to answer questions. They might not have a well planned schedule. They should be able to schedule things or give you time periods when they are more likely to be available though.
Anyway you should usually not wait much before asking a question. If you haven't found an answer or don't understand something after a 20 minute search on the mailing list archive, the code, the documentation and Google, it's high time to ask a question or ask to have a chat. Please try to search for 5 to 10 minutes before asking though, and please let your mentors know how you searched, so that they can perhaps help you be more efficient in searching for answers.
In general being as open as possible about everything related to your work, like what you don't know or don't understand, possible mistakes you have made and are still making, how you are searching when there is something you don't understand, which commands you are running, and even how you are feeling, helps a lot in resolving issues and moving forward.
If you plan to have a vacation or if something might prevent you from contacting your mentors, from updating them weekly, or from working on your project for some time, please let them know in advance.
We require that you store and regularly update your current work in public repos on GitLab or GitHub (or maybe Gerrit, gitolite, etc, but please discuss it with us before choosing something other than GitHub or GitLab). Usually a single repo forked from an official git.git repo maintained by Junio (like https://github.com/git/git) is enough, and you probably already have one.
It unfortunately happens that people stop working on their in progress project, either after the mentoring program is finished, or sometimes during the mentoring program, and we might want to reuse their work later. Often for example it takes a number of mentoring programs to finish a big project and you have to continue a project from where it was left by someone else.
Having everything in one, or a few, public repositories makes it easier to continue some work and also to test or contribute to it occasionally. So making your work available this way and frequently linking to your repo and the branches and commits in it you have worked on (for example from your blog posts and emails to the mailing list and your mentors), can help you get comments, code contributions, bug reports, etc, which will move your project forward.
It's a good idea to have your mentors review your patches or patch series or branches on your repo before sending them to the mailing list. It's OK though if you want to sometimes send a draft patch or patch series directly to the mailing list to get as much as possible everyone's feedback on something. You should mark them as [RFC] (request for comment) or [WIP] (work in progress) though.
A good way to have your mentors review something is to send them a link to it on your public repo. This way they can comment there and maybe make suggestions that you can easily apply. You could also directly send them your patches as emails if they are OK with it.
When you update your work after having received feedback from your
mentors or others, it's nice if instead of updating the same branch,
you could make changes, on a new branch. For example, if you are
working on git bisect you could make some initial changes on a
branch named bisect1, then, after receiving some comments on it, make
further changes on bisect2, and so on. This way your mentors and
others could check what you did using a diff, or a range-diff, between
the branches.
Before you ask your mentors to review something, even if it's in the draft or work in progress state, it's a good idea to make sure that you have put some effort in writing a good commit message for each of the commits you'd like them to review. Without a commit message (with a title and a body) explaining the purpose of your patch, it can be difficult for your mentors (or anyone actually) to tell if it makes sense.
If you know that something is missing in your patch, it's a good idea to add [WIP] or [RFC] in the title and to add comments somewhere about things that are missing, (like /* TODO: XXX */ comments in the code for example), so that your mentors know which parts of your work are not finished.
A good time to send a link to a branch you are working on to your mentors and ask them to review it, is typically when the commit message and the code look good, and when it compiles without warnings and passes existing tests, but when you haven't yet written the documentation and the new tests. You can then work on the new tests and documentation while your mentors review the code. Even then, please say that documentation and new tests are missing.
That said, it's OK to send something when a number of parts are missing, including maybe some parts of the commit message and when the code does not even compile, as long as you describe clearly what you'd like to do, what are the issues you are facing and what is missing or not yet finished, so that your mentors don't have to guess or tell you that things are missing or should be improved when you already know it.
The goal is really to have efficient discussions for both you and your mentors, so that your project can move forward fast with as few misunderstandings as possible and as little frustration as possible.
As much as possible you should work on different parts of your work in different branches, and avoid having similar commits you are working on in different branches.
It's much better to work on many small branches and patch series that can be regularly sent or resent to the mailing list, rather than on a single big one that can be sent only at the end when everything looks good.
It's up to you if you prefer to wait until your mentors have reviewed everything and found nothing wrong with your patches, which could be a good thing as it would likely decrease the reviewers' work on the mailing list, or if you prefer to send your patches when you think they are ready.
You might acknowledge your mentors' help with the work you are doing by adding a "Mentored-by: Mentor Name mentor@email" trailer for each of your mentors in the commit message of all the patches you send. We recommend doing this systematically instead of spending time finding which mentor helped or not on which patch.
Basically sending patch to the mailing list is the same process as when working on a micro-project.
A few things that you might want to do are:
-
Make sure your mentors are Cc'ed on all of your patches.
-
Make sure everyone who commented or got involved is also Cc'ed.
-
Make sure Junio is among the recipients (in the "To:" header) if your patches have been reviewed.
-
Consider adding the "Mentored-by:" trailers discussed above.
-
Consider adding some "Helped-by:", "Reviewed-by:" or "Acked-by:" trailers if relevant.
-
Don't forget bumping up the version of the patch series.
-
Don't forget using [GSoC] or [Outreachy].
-
Don't forget using [RFC] or [WIP], if it's relevant.