Social Aspects of Lesson Maintenance

Overview

Teaching: 30 min
Exercises: 25 min
Questions
  • What is the role of a Maintainer in interacting with contributors?

  • How will I interact with my fellow Maintainers?

  • What is the Carpentries etiquette for working with GitHub?

  • What types of PRs am I likely to see and how should I handle them?

Objectives
  • Apply Carpentry pedagogical principles to curricular decision making and interactions with contributors.

  • Use the GitHub flow contribution model and Carpentry GitHub etiquette to contribute to Carpentry lessons.

  • Determine how you and your co-Maintainers will communicate and how you will divide responsibilities for your lesson.

  • Recognize complications involved with different types of PRs and practice dealing with difficult PRs diplomatically.

Interacting with Your Fellow Maintainers

As a Maintainer, you will be part of an overlapping set of teams. From smallest to largest, these include:

Find Your Technology Team!

For our exercises today, we will be working with your Technology Team. In the Etherpad, next to your name, write the name of your lesson (including whether it is a DC or SWC lesson). Identify your group number and put it next to your name:

1) R Maintainers 2) Python Maintainers 3) SQL Maintainers 4) Unix / Git / and other Maintainers

The overall Maintainer team communicates via our mailing list. Please make sure you are signed up, as this is the primary communication channel for all Maintainer-related information. We also have monthly meetings to discuss topics relevant to the Maintainer community. You can find the times for these meetings on the community calendar and on the Maintainer Etherpad.

There is a separate email list for people going through Maintainer onboarding. To sign up for this list, visit our Google Group.

It is important to stay in touch with your Lesson Team. All Lesson Teams work differently, and you will need to find a communication style and distribution of work that works for you. We recommend that, at a minimum, your team meets by video-conference once a quarter to set priorities and deal with existing concerns.

There are several decisions that your Lesson Team will need to make about how you will work together. Here are some issues you should consider:

Make a List (10 min)

With your break-out group, discuss the points above and add to this list. What are other things that you want to communicate about with your Lesson Team?

Follow-up Homework

Get in touch with your Lesson Team to schedule an initial meeting. At this meeting, be sure to discuss the issues in the list generated above. Communicating by email can also help to set the stage for your initial meeting and clarify any of these items after the meeting.

Getting Set up on Zoom

The Carpentries use Zoom for video-conferencing. You can get a personal Zoom account by going to https://www.zoom.us/ and clicking the SIGN UP, IT'S FREE button in the upper right corner. After signing up, click Go to My Account to see your personal Zoom meeting link. You can invite people to your personal meeting by sending them your personal meeting ID URL. Free accounts have a 40-minute limit on meetings with 3 or more participants, but meetings can be restarted.

Interacting with Other Contributors

Maintainers represent the Carpentries on some of our most active online spaces - our GitHub repositories. As a Maintainer, you will often be the first point of contact for people new to the Carpentries community.

Igor Steinmacher, a computer scientist who researches retention of open source contributors, provides a set of recommendations based on his research on how to reduce barriers to new contributors becoming part of your community. While some of these are more specific to software projects, some are very applicable to our (or any) community:

Preparatory Homework

Pick one of the points above and be prepared to discuss how you feel the Carpentry community does overall in meeting this recommendation. Can you identify ways in which we could improve?

Discussion (10 min)

In your breakout groups, share your thoughts on the points you selected. Add your notes to the Etherpad.

When interacting with contributors, whether new or old, we want to be sure to embody Carpentry values around communication and teaching and learning.

Preparatory Homework

Review the episode on Motivation and Demotivation from Instructor Training. Make some notes for yourself about how the factors discussed in this episode should influence the way we interact with contributors.

Solution

  • Teach Most Useful First - we can (and should) politely turn down contributions that take the material out of the scope of the novice learner or that involve unnecessary and distracting technical detail.
  • Actual Time - everything will probably take longer for learners than it does for you. Limit new additions to the materials and encourage cutting material where needed.
  • Things You Shouldn’t Do in a Workshop - these are also things we shouldn’t do in a PR or Issue conversation.
  • Imposter Syndrome - be encouraging to new contributors, even if they make a formatting mistake.
  • Accessibility - take seriously any comments a contributor makes about accessibility issues.
  • Inclusivity - avoid unnecessary use of gendered pronouns and other exclusive language.

Discussion

With your breakout group, discuss your responses to the preparatory homework above. Add your notes to the Etherpad.

Some summary text.

GitHub Etiquette and Processes

Preparatory Homework

Read the Carpentry Contributor Guidelines and work through those instructions to make a contribution to this repository. Even if you’re already familiar with Git and GitHub, follow those instructions carefully. Pay attention to anything that was unclear or didn’t work as you expected. Be prepared to discuss.

Discussion

How easy was it to use our Contributor Guidelines? Was there anything unclear or difficult? What things do you think will be confusing for new GitHub users?

In addition to formal contributor guidelines, the Carpentries have an unstated (until now!) but commonly used set of community norms for working with GitHub. These include:

Being open to new contributions while keeping the lessons sleek and teachable is a difficult balancing act. It’s ok to say no to a contribution when it doesn’t add anything useful to the materials, goes beyond the scope of the lesson, or introduces unnecessary complexity. Even when saying no, however, we want to have positive interactions with contributors and let them know that their involvement is valued. GitHub’s OpenSource Guide for Maintainers has an excellent discussion on learning to say no.

Preparatory Homework

Read “Learning to Say No”. Be prepared to discuss how you can implement these suggestions as a Maintainer.

Exercise

With your breakout group, select one PR or Issue that has been open for > 6 months. Read the comments and discuss what the problem is (i.e. why hasn’t the PR been merged). Draft a response to the PR/Issue in the Etherpad. If you’re comfortable doing so, add your response to the conversation and tag the other Maintainers for the lesson.

Key Points

  • You’re part of the Maintainer team now! Stay in touch with your team.

  • It’s ok to say no.