Onboarding Guide 2023
This guide is meant to establish guidelines and provide important resources for contributors and mentors participating in the GSoC and Station1 2023 programs. Original text included in this onboarding guide is courtesy of the GSoC Mentor Guide and GSoC Contributor/Student Guide and is modified by MDAnalysis.
The MDAnalysis community subscribes to a Code of Conduct that all members must agree and adhere to. Please read it carefully.
If you want to report a Code of Conduct violation, please email the Conduct-mail group or fill out this form. All reports will be kept confidential. Only MDAnalysis Code of Conduct Committee members can view messages sent to the Conduct-mail or the online report form. The online form gives you the option to keep your report anonymous or request that we follow up with you directly.
Public communications are preferable to private ones. Within MDAnalysis, we make use of multiple means of communication on different complementary platforms. Instant methods, like our Discord server (join using this invite link), are great for getting a quick answer/suggestion or for interactive discussion, but should not be relied on if you would like to reference back to a thread of the discussion. In situations where you would like to keep a thread to reference back to or are having discussions about things relevant to the wider MDAnalysis community, it is best to use the public GSoC (for GSoC contributors), discussion and developer mailing lists. Contributors are expected to submit their code as pull requests (PRs) on GitHub early so that constructive discussions can occur on the PR itself (and in related issues). If you are addressing a personal matter and must communicate by email, it is best to ensure there are always more than two individuals in the loop (e.g., contributor and all assigned mentors).
Although some people prefer text-only communication, mentor-contributor groups should talk on the phone or video-chat during key milestones of their respective program. Hearing a voice or seeing a face can help people feel more connected, creating a sense of mutual respect and responsibility. During the initial meeting, mentor-contributor groups should establish meeting frequencies and platforms (e.g., weekly or bi-weekly video chats) to be used for the duration of the program. In addition, mentor-contributor groups should meet…
- … at least four times throughout the GSoC program:
- at the start of the community bonding period
- at the start of the coding period (after the contributor’s first blog post)
- after the midterm evaluations
- after the final week
- … at least three times throughout the Station1 program:
- the first day of work
- halfway through the program
- before the capstone poster presentation
Mentor-contributor groups should swap contact information between each other and the org admins right away. If your contact information changes, be sure to tell people. The org admins can always be reached through the Discord server (jennaswa [she/her]#0380, OliverBecksteinASU#6713, highspeedmode#6713), MDAnalysis mailing lists, or by email (community@mdanalysis.org, orbeckst@mdanalysis.org, ialibay@mdanalysis.org).
Here is a summary of important dates throughout the GSoC 2023 program timeline.
Below is a summary of important dates throughout the Station1 program timeline:
- June 13 - First day of internship orientation
- August 11 - Capstone poster presentation
- Official GSoC 2023 program website
- GSoC Mentor Guide
- GSoC Contributor/Student Guide
- Official Station1 Frontiers Fellowship website
In addition to the guidelines laid out in the MDAnalysis Code of Conduct, contributors should embrace the following principles, guidelines and actions to ensure the program is a welcoming and positive experience for all participants.
- Be open and transparent. Open source communication can vary a lot, but a core value held in common is that sharing code is good. Working on code together means a lot of things: transparency, directness and cooperation are common words to describe the process. Disagreements about code are respectfully aired in public. Do not fear the process, and practice participating publicly. Ask questions if community members use terminology or abbreviations that you do not understand, as the clarification could also be a benefit to others.
- Be proactive. If you rely solely on your mentor to keep track of and enforce the schedule of work, your project is almost guaranteed to fail. Be proactive in keeping the schedule you’ve agreed to and proposing modifications before deadlines pass. To be respectful of your mentors’ time, come prepared to meetings. Never be afraid to ask questions, but remember you are going to be more successful in receiving a good answer if you try to be specific and do a bit of background investigation first.
- Be communicative. While it is important to be independent and work through challenging tasks on your own, you should absolutely make sure you’re interacting often with your mentors through mutually agreed upon communication channels. As you implement each phase of your project plan, ask your mentor for feedback on the code as you go. Avoid working for two weeks on a chunk of code that is headed in the wrong direction. Where possible, be sure to promptly (i.e., within 2 business days) respond to requests for information and commit useful code. If you need to miss a deadline, make sure you communicate this to your mentors well in advance.
- Be upfront about availability. Be sure to keep the org admin and your mentors informed about when you may be unavailable for more than a few days or near milestones in the program timeline. It’s okay as long as you let them know as soon as you can so you both can work on a reasonable schedule and project milestones together. You can plan to make up for lost days by extending the standard program length or having heavier coding weeks to accommodate the missed time.
- Be patient. MDAnalysis involves individuals (including your mentors) working across different cities, countries and continents. Due to differences in time zones, as well as other time commitments, mentors may respond to you outside of your normal working hours and need 1-2 business days to reply. Remember that you are primarily working with volunteers, and other peoples’ time is just as valuable as your own.
- Be receptive to feedback. Hearing criticism can be hard, but asking for and receiving constructive criticism about your project from your mentors, the larger MDAnalysis community and your peers is an invaluable exercise to help you write the best code possible. Do your best to listen, learn and incorporate feedback into how you work.
First, stop and remember that your mentors are volunteers and have non-GSoC or Station1 responsibilities. If you didn’t get an immediate response outside of scheduled meeting times either on Discord or email, be patient. If your mentors missed a meeting, then a gentle message along the lines of “did I mix up our meeting time” to your mentors is a great idea. If you don’t hear back, then contact the org admins.
Do not wait until the end of the evaluation period to let the org admins know that your mentors were not communicating with you. If for some reason your mentors haven’t responded to you within 5 days (and didn’t tell you they were going to be unavailable), then contact the org admins.
Remember that everyone is coming from different backgrounds and has different communication styles. You might both be communicating in a second language. Providing project critique is part of a mentor’s job. That being said, if you feel like one of your mentors is being unduly harsh and it is affecting your project success, the best approach is to talk with your mentors about their communication styles in a non-confrontational manner. If you still feel like things are not resolved after your conversation, talk to the org admins.
Our Code of Conduct clearly states that we do not tolerate any form of harassment by anyone, including mentors. If you would like to file a report, you may contact the org admins or follow MDAnalysis’s reporting guidelines. You may also follow NumFOCUS’s Code of Conduct violation reporting guidelines if you would like to contact a third-party outside of the MDAnalysis community.
Please reference the GSoC Contributor/Student Guide for an overview of how GSoC works, including information on the different phases, evaluations, final submissions, and payments.
Please reference the Station1 Frontiers Fellowship website for an overview of how Station1 works, including information on the different programmatic components.
In addition to your mentors and org admins for the GSoC or Station1 programs, you will likely interact with members of the wider MDAnalysis community through public forums and the code review process. This includes all developers that have expressed interest in mentoring for the GSoC or Station1 programs, as well as the MDAnalysis core developers.
During the initial mentor-contributor meeting, you should establish a method with your mentors upfront for communicating progress updates throughout the program. We ask you to write a blog post every two weeks to summarize your progress. This will also help you receive feedback from the wider community and track information that you will need to include in your final work submission. As a general rule of thumb, you could answer the following questions in your posts:
- What progress have you made since your last post?
- What commits did or didn’t get merged since your last post?
- What went well, and what accomplishments are you proud of?
- Have you encountered any challenges that are impeding your progress?
- What goals do you have for the next two weeks?
Breaking down your project into smaller tasks helps in many ways:
- It gets you started! You have a smaller, well-defined task to work on which is easier to manage.
- Mini-goals help create a road map to get to the final output you’re trying to produce.
- Smaller goals are less daunting, and completing a small goal gives you the confidence to tackle the next one.
Don’t be afraid to ask for code reviews as frequently as you need them. If your mentor tells you that you are going about something the wrong way, you don’t want to find out after writing a ton of lines of code.
Keeping a log of your progress is a great way to monitor progress both for yourself, your mentors and anyone else. It is also valuable in cases when you need to reconsider a decision and figure out why you made certain choices in the first place. Blogging is a good way to achieve this, since you may get good advice from people that you normally wouldn’t communicate with.
It is very likely that your mentors are in a different time zone than you are. Take this into account while you’re preparing your project plan. Time zones should be included for any meeting times (helpful World Clock here), and UTC is often the best time zone to use, since it is not affected by Daylight Savings Time.
Things don’t usually go the way you plan them. Make sure you have room for unplanned changes. It’s best to keep aside some buffer time that you can use in case you digress from your original plan.
Here are some general rules you can follow to make your code easier to integrate into the MDAnalysis code base:
- Follow the documentation guidelines.
- Make sure the tests pass! Learn to run tests locally (see the User Guide: Tests in MDAnalysis) and always look at the results for the continuous integration (CI) tests that are run automatically when you add a commit to your PR. For more information, also check out Google’s suggested Test Driven Development workflow. In general, it is best to establish an iterative workflow with small, clearly defined, quantifiable goals. Making smaller PRs is much better than a single mega contribution. Splitting your work into smaller, modularized code contributions will allow you to make a much more rapid process, because the code can be more easily tested and reviewed.
- Document your code with both docstring and, where relevant, in-code comments. That being said, if your code requires a lot of in-code comments, then you should consider if you should instead use easier to understand variables, or restructuring of your code to reduce complexity. Include lots of useful comments in your code.
- Document exactly what kind of environment you wrote the code in, and whether certain things may be dependent on your operating system or platform.
- Read through recent commits to the repository location that you would like your code to be in. You will often learn about something relevant to your code, such as a macro that makes your life easier or a special trick for avoiding bugs.
- Commit often. You can always maintain a local branch of the code to which you keep committing regularly. This keeps you from losing work and gives you something concrete to show your mentors and get feedback on. Any code that you commit will be automatically tested on all platforms that MDAnalysis supports and so you’ll immediately get valuable feedback on the quality of your new code.
- Take the feedback on your code positively. Appreciate the comments and suggestions you receive, and use them for your next commit. You can also ask other GSoC or Station1 contributors to review your code for you and give you feedback. Use other students in your community and the GSoC and Station1 programs as a resource.
Although you likely have worked through many of these steps in submitting your first PR(s) to MDAnalysis, the community bonding period and first month of your program is the perfect time to ensure everything is in working order.
Have a look at the sections of the User Guide explaining how to contribute. There are detailed explanations on how to set up a developer environment and how to contribute to the MDAnalysis codebase.
Once you get your development environment setup, start practicing! Look through MDAnalysis’s open issues, do a few practice commits and work on understanding how source control works within the project. Whenever you add new code, you should get in the habit of creating an appropriate test case that checks that your code is working as it should. Code without tests will not be merged into MDAnalysis — MDAnalysis is scientific software and so we prize code correctness over any other quality. Tests are of vital importance to maintaining the health of the whole project. Brush up on any new skills and start asking questions.
Connect with your mentors and other GSoC or Station1 contributors. Set up a blog, get involved on the GSoC (for GSoC contributors), discussion and developer mailing lists and the Discord server and in general, start interacting with the development community. Don’t be afraid to ask your questions, and don’t be afraid to answer!
We also look forward to introducing you to the wider community through the MDAnalysis Blog. After your initial meeting with your mentors, please contribute to the introductory blog post by making PRs to a skeleton blog post to fill in a short summary of your proposed project and a biography sketch. For inspiration, please have a look at our announcements for our 2022, 2021, 2020, 2019, 2018, and 2017 students.
The Community Bonding Period and/or first month of your program is when you work out further details of your project plan. This is the time to work with your mentors to schedule regular upcoming meetings and to set expectations for your interactions and how your progress is measured during the program. Make any project adjustments you may now recognize as necessary based upon getting your development environment setup and your new understanding of how MDAnalysis works. Have you informed your mentors of any planned absences? This is a crucial time to let your mentors know if your plans changed since you first wrote your proposal and now you will have limited availability for some period during the program for whatever reason.
In addition to the guidelines laid out in the MDAnalysis Code of Conduct, mentors should embrace the following principles, guidelines and actions to ensure the program is a welcoming and positive experience for all participants.
- Be available. GSoC and Station1 contributors are not experienced project members and will need more time and support to contribute code than the core team. Mentors should expect to spend 2-4 hours per week for each contributor. Some weeks may be more, some weeks may be less. More time spent during the community bonding period and the first few weeks of the program can lead to more successful and engaged contributors.
- Be responsive and communicative. While it is important to give your contributor the independence to work through challenging tasks on their own, it is important to ensure your contributor is not left stuck. Be patient, communicate often and be sure to talk with contributors about roadblocks. Be sure to promptly (i.e., within 2 business days) respond to requests for information and or requests for comment on committed code. If you, the mentor, need to miss a deadline, make sure you communicate this to your contributor well in advance.
- Be upfront about availability. Be sure to keep the org admins, co-mentors, and your contributor(s) informed about when you may be unavailable for more than a few days or near milestones in the timeline. Coordinate beforehand to ensure contributors have sufficient work, co-mentors are available as a secondary mentor and co-mentors or org admins are able to complete evaluations while you are offline.
- Provide a safe environment. Create an environment in which your contributor feels comfortable enough to ask questions that may sound “stupid”. This will help the contributor to avoid getting stuck and foster positive mentor-contributor and contributor-community relationships. It’s likely the contributor will ask questions which are answered somewhere in the MDAnalysis documentation. However, do take a few moments extra to politely point to the information, or you’ll risk the contributor feeling reluctant to ask the next time they have a question.
- Be inclusive. Public communications are generally preferable to private ones. If you’re asked a question which someone else in the project could answer better, put your contributor in touch with them.
- Be encouraging. A simple “thank you” when contributors publish code, send an email to a mailing list or make other contributions goes a long way. At the completion of each milestone, you and your contributor should celebrate the accomplishment and reflect upon it. Reinforcement of a contributor’s tangible accomplishments encourages them to stick around and helps create life-time contributors.
- Be flexible. In addition to collaboratively setting expectations with your contributor, it is important to decide in advance what happens when project goals aren’t met. Remember to be flexible if your contributor has made good progress or has obviously worked hard but needs to re-scope the project at mid-term. Be ready to revise project plans if an unexpected requirement or bug occurs.
If your contributor has a full-time job or is attempting to defend a graduate thesis during the summer, that is probably not going to work if they are trying to do a 350 hour project. If your contributor has every single minute of every single day completely booked, any unexpected event, such as getting sick or a family emergency, derails this plan beyond repair. If your contributor is unable to commit to a specified time schedule, they may need serious help with time management. You may need to give them extra support in setting mini-goals for each week and keeping a log to make and track progress. Directing them to the Tips for Success in this onboarding guide may help them hone their time management skills.
For GSoC projects, it is also possible to change the project from full-time to part-time status. This can be done either by 1) changing the project size or 2) changing the project length. Project sizes can only be changed by org admins from large (350 hours) to medium (175 hours). Otherwise, org admins must contact Google admins to make the change for them. If mentors and contributor(s) decide they would like to extend the timeline of the project, the org admins can adjust the schedule of the project to 10, 14, 16, 18, 20, or 22 weeks.
If your contributor continues to procrastinate or offer excuses for missing milestones and deadlines, it is okay to fail them during their evaluations.
If you didn’t get an immediate response outside of scheduled meeting times either on Discord or email, be patient. If your contributor missed a meeting, then a gentle message along the lines of “did I mix up our meeting time” to your contributor is a great idea. It may be that your contributor was in such a deep “coding zone” that they forgot the meeting, and you can reschedule it for later, or they may have other environmental or personal issues going on. First, you should speak to your contributor about the situation. If after understanding why the meeting was missed you feel your contributor is not taking the process seriously, it is time to initiate a conversation with your contributor about their underperformance. If things do not resolve themselves, contact the org admins to intervene. If there are still no improvements in behavior, mentors and org admins can decide collectively to fail the contributor during their evaluations.
Even after requesting better documentation/commenting of code or providing clear steps for working towards milestones, you may encounter a contributor that does not heed your advice and goes in other directions. As open source requires constant interaction between community members and the ability to consider and accept feedback, the contributor would need to learn this valuable skill to succeed in this line of work. If after trying several strategies for communication and goal setting you see no signs of improvement, you should contact the org admins to intervene. In the case of no improvement, mentors and org admins should collectively decide whether to pass or fail the student during their evaluations. It is important to keep in mind that as a mentor, it is your job to ensure the contributor has all of the tools they need to improve. If the student is putting in consistent effort but is just not quite producing the quality of code you would hope for, it is probably best to pass them to ensure they are recognized for their time and effort, but to provide detailed explanations of your concerns. However, if you feel you have done your due diligence and the student is just simply not taking the process seriously, it may be time to fail them.
When working with people for the first time, a best practice is to assume that they do not mean any harm. If your contributor makes a comment that offends another member of the community, it’s appropriate and constructive to speak up and address the issue. Assuming that the comment was the result of misunderstanding, language barriers or cultural differences, rather than a result of malice, allows you to ask questions and help your contributor adjust to the community’s communication style. You can offer an explanation on how they could behave or phrase their comments differently in the future.
If your contributor has clearly made an intentional breach of ethics and violated the Code of Conduct (e.g., in the case of plagiarism or harassment), it is important to clearly explain to your contributor why the behavior is unethical and will not be tolerated. You should report the incident to the org admins and may follow the MDAnalysis reporting guidelines to report a Code of Conduct violation. In this case, the contributor should fail the GSoC program and be reported to the Google Summer of Code organizers (for GSoC contributors) or Station1 organizers (for Station1 contributors).
It is okay to fail contributors if they do not meet expectations. However, the primary goal should be to help the contributor develop into a better programmer. If you must fail a contributor, the most important thing is to ensure you thoroughly explain why you are failing them. They can then use it as a learning experience, as failure can sometimes teach more than success does. A failing evaluation should not come as a surprise: Communicate problems to the contributor and org admins right away and document them (date and summary) in case you want to reference them later.
Successful mentors set expectations at the start of their projects. This includes communication frequency, project goals, availability and ways of delivering feedback. While the mentor should take the lead in expectation setting, the process of creating and documenting the expectations must be collaborative. Contributors and mentors need to agree on what is expected.
Set achievable goals. Rather than defining the project as one giant chunk, help your contributor break the project goals down into smaller pieces or “inchstones” that allow a change in direction if necessary.
Anticipate time away. Make sure to set expectations for known or planned time away from the project. Talk about how many hours or deliverables per week would be reachable goals and what amount would be a good stretch goal. The GSoC program allows for a flexible coding period anywhere between 10 and 22 weeks (which can be changed at any point up to the final evaluation) to take into account anticipated time away.
Target completion dates for each milestone. In reality, completion dates are going to move. Nonetheless, a target date gives you a time frame for closure and helps control “scope creep”. Coach your contributor in how to recognize that a milestone is going to be missed, and to notify the project participants before the date passes.
Plan for environmental issues. Ask about the weather and local stability of public services. Is your contributor using the cafe down the street for Internet access? Are there seasonal weather conditions that may lead to flooding and the subsequent inability to turn-on one’s computer? Work out a plan to address these types of environmental issues that can affect both communication and output.
Status reports are an important communication tool and important in making sure that time-line slippages and scope creep are addressed in a proactive manner.
Check off associated milestone tasks. Find a way to keep track of tasks, and then indicate when they are completed. This can be as simple as keeping an informal to-do list that is referenced in weekly status reports.
Set an expectation of prior notification of missed deadlines. Make sure your contributor understands that it is important to notify you well in advance of deadlines that are going to be missed. If your contributor misses a deadline, make sure you discuss why. Helping your contributor understand where they become bogged down or stuck helps with future strategic plan development.
GSoC or Station1 contributors may experience public critiques of their code for the first time through participation in the program. Here are some ways that you can help contributors prepare for code review:
- Provide example mailing list threads or a list of the types of questions that are asked about code.
- Direct contributors to review coding standards that apply to your project.
- Go through an example code review on the contributor’s first code sample submission that matches as closely as possible the process for the type of contribution typical for the project (for instance, contributions to MDAnalysis core modules undergo much more detailed review than contributions to an MDAKit).
Make sure criticisms are constructive. Phrase suggestions positively. If criticism is personal in nature (e.g., tone of an email, timeliness or other non-code issues), deliver it in private rather than in a public forum.
Make a point to give positive feedback. When a contributor completes a task on time, and especially when they exceed your expectations, let them know!