Maintainers Handbook#

The Carpentries Maintainers work with the community to make sure that lessons stay up-to-date, accurate, functional and cohesive. Maintainers monitor their lesson repository, make sure that pull requests and issues are addressed in a timely manner, and participate in the lesson development cycle including lesson releases. They endeavour to be welcoming and supportive of contributions from all members of the community. This community of practice is a great place to learn to collaborate effectively in Git and GitHub.

Roles and Responsibilities#

The Carpentries teaches 400–600 workshops each year, meaning our lesson materials are being used practically every day for synchronous, guided learning. Making sure our lessons keep working without interruptions is therefore our number one goal for maintenance.

A secondary (but still extremely important!) goal is ensuring that the spaces we use for lesson development and maintenance are just as welcoming and inclusive as our workshops.

Ensuring that our lessons are on the cutting-edge of new technology and tooling is not a priority for The Carpentries. Although we do want our materials to stay relevant, it is far more important that our lessons remain pedagogically sound and technically viable, than that they represent the latest and greatest new developments in the field.

With these goals in mind, The Carpentries expectations of Maintainers are to:

  • Monitor the lesson repository and make sure that pull requests (PRs) and Issues are responded to in a timely manner (even if that response is “sorry, this is out of scope”),

  • Do not introduce new errors into the lesson

  • Quickly fix anything that is unambiguously an error or that negatively affects workshop learners

  • Be receptive and welcoming to suggestions for improving the lessons

  • Evaluate all contributions in view of The Carpentries pedagogical model:

    • Teach what is most relevant and useful for learners.

    • Avoid unnecessary jargon and detailed explanations. Always ask yourself whether it is necessary for the learner.

    • Keep language motivating.

    • Meet learners where they are.

    • Emphasise the importance of continued learning and improvement.

Maintainers are responsible for:

  • Routinely:

    • Ensuring reasonable response time to all submitted Issues and PRs. At a minimum, ensuring all Issues and PRs are acknowledged within two days.

    • Quickly addressing issues and PRs tagged as “bug”s.

    • Submitting Issues as they arise.

    • Adhering to the Code of Conduct and alerting the Code of Conduct Committee to any potential violations.

    • Identifying potential new Maintainers based on their review activity.

  • Periodically:

    • Helping prepare lessons for publication.

    • Bringing in updates to the lesson template.

Maintainers represent The Carpentries community and should strive to embody The Carpentries philosophy, by:

  • Recognising the importance of communication and being welcoming to all contributors.

  • Giving feedback to contributors using The Carpentries model:

    • Find what’s good. Be specific about improvements needed. Use motivational language.

  • Evaluating lesson contributions in light of Carpentries pedagogical model:

    • Teach what’s most relevant and useful for learners.

    • Avoid getting bogged down in technical details.

    • Keep language motivating.

    • Emphasise the importance of continued learning and improvement.

Onboarding#

New Maintainers go through an onboarding process, led by a member of The Carpentries Curriculum Team and the Maintainer Community Lead. Maintainer Onboarding takes place at least once per year. New rounds of onboarding will be announced on The Carpentries blog and main communications channels (discuss TopicBox, general Slack channel).

The curriculum for onboarding new Maintainers is available as a Maintainer Onboarding Lesson.

Offboarding#

A yearly email with a one-question survey will be sent to Maintainers in mid-to-late January. If the Maintainer responds “yes” to this survey, they will remain a Maintainer for the next year. If a Maintainer replies “no” or does not respond within a month of receiving the survey, they will become an alumnus Maintainer and their permissions to their repository will be revoked. Active Maintainer status can be restored at any time by contacting the Maintainer Community Lead. The proposal for yearly Maintainer check ins has more detailed information. If a Maintainer would like to step away from the role outside this schedule, they should inform the Maintainer Community Lead and the other Maintainers on their lesson(s).

Communication and Collaboration Spaces#

  • Slack:

    • The invite-only #maintainers channel on The Carpentries Slack workspace is a platform for the whole community to ask questions and engage in discussions around the subject of lesson maintenance. The Maintainer Community Lead and Curriculum Team members will also cross-post announcements relevant to the community to this channel.

    • We recommend that Lesson Maintainers browse existing channels in the Slack workspace, for any that are relevant to the topic/domain of their lesson.

    • It can also be helpful to create a new channel for your lesson, as a space for you to discuss the development process with collaborators, and for community members to ask questions about the lesson.

  • The Maintainers mailing list is used for announcements relevant to Lesson Maintainers.

  • Monthly Calls:

    • The Carpentries Curriculum Team organises monthly Maintainer Community Calls on the third Wednesday of the month at two times to allow maintainers from around the globe to join during more convenient hours. Minutes are recorded in the maintainer-resources repository.

Community Calendar#

Once scheduled, all Maintainer Community Calls are listed on our Community Calendar. You can add relevant events to your personal calendar from there by clicking on the event you would like to attend.

Collaborative Notes#

Below is a list of Etherpads relevant to serving as a Lesson Maintainer.

GitHub#

Google Documents#

Slack#

Join the Carpentries Slack workspace. To follow conversations relevant to this role, you should join the following channels:

  • The invite-only #maintainers channel on The Carpentries Slack workspace is a platform for the whole community to ask questions and engage in discussions around the subject of lesson maintenance. If you are a Maintainer and do not already have access to this channel, please contact the Maintainer Community Lead.

  • We recommend that Lesson Maintainers browse existing channels in the Slack workspace, for any that are relevant to the topic/domain of their lesson.

  • It can also be helpful to create a new channel for your lesson, as a space for you to discuss the development process with collaborators, and for community members to ask questions about the lesson.

If you are new to Slack, please check out our Slack Quick Start Guide.

TopicBox#

You can access The Carpentries mailing lists from TopicBox. Below is a list of those relevant to the activities and programs covered by this handbook.

To join one or more Carpentries mailing lists, you will need to create a login on the site. Once you have done this, you can scroll through the list of groups and click “Join the Conversation” (for open mailing) or “Request to Join” (for those mailing lists requiring administrator approval).

Step-by-Step Guides#

Using Issue Labels to Promote Collaboration#

GitHub allows the Maintainers of a repository to add contextual information to Issues and Pull Requests in the form of labels. Two labels, used by The Carpentries and in many repositories across GitHub, can be deployed to increase the visibility of your lesson and encourage community members to contribute to its development.

The “help wanted” label should be used to highlight issues with which you would welcome additional help. The Carpentries website includesa Help Wanted page, which can automatically list every issue labelled “help wanted” on repositories from The Carpentries, Software Carpentry, Data Carpentry, Library Carpentry, CarpentriesLab, and The Carpentries Incubator. Find out how to include issues from your lesson repository on the Help Wanted page by reading theInformation for Maintainers on the page itself.

The “good first issue” label should be used to identify issues that would make a good entry point for newcomers searching for a way to contribute to your lesson. The work needed to close an issue with this label would typically not require an extensive knowledge of the structure or intricacies of your lesson repository, or an expert understanding of the content. The “good first issue” label is used so extensively that GitHub provides a page at[repository URL]/contribute for every repository, listing issues with this label.

Adding Topic Tags to a Lesson Repository#

Official Lessons in The Carpentries Lesson Programs are` <https://carpentries.org/community-lessons/>`__listed on The Carpentries website, based on metadata describing the lesson. This metadata is added in the form of topic tags on the lesson repository. These topic tags should be set as soon as possible after the lesson has been created or added to the Incubator. Some are essential and taken from a limited set of values, while others are more flexible. The table below has guidance about the types and number of topic tags each lesson repository should have.

Category

Example

Number

Description

Lesson

lesson

1

Must be lesson to be listed on the Community Developed Lessons page

Location

data-carpentry

1

A description of what lesson program the lesson belongs to with words separated by hyphens (i.e software-carpentry, data-carpentry, and library-carpentry)

Language

español

>0

The language(s) the lesson is available in

Stage

stable

1

The current development stage for the lesson

Domain

microbial-ecology

1-2

The high-level domain(s) of the lesson for a general categorization

Tools

python

1-3

The main tool(s) taught in the lesson

Skills

taxonomic-classification

1-3

The main skill(s) taught in the lesson

The Curriculum Team will support you in setting appropriate topic tags for your lesson. To help ensure consistency across all lesson repositories developed by The Carpentries community, please refer tothis listing of topic tags currently in use in The Carpentries Incubator, and re-use these values where appropriate, creating new topic tags where no pre-existing label exists for your lesson.

Informing Community Members about a Period of Absence#

If you plan to temporarily step away from the role of Maintainer, e.g. parental leave, exam season, etc, it can be helpful to your fellow lesson Maintainers and potential contributors to let them know. Here are some steps you can take to notify the community about your temporary absence/unavailability:

  1. Set a status and mark yourself as “busy” on GitHub:

    1. Log into GitHub.com

    2. Click on your profile picture at the top-right of the window

    3. Select “Set status”

    4. In the “What’s happening?” box, write a short statement that lets other users know you are unavailable. You don’t have to tell people why - your status could be “temporarily unavailable” or “unavailable until DATE” to tell people when they can expect to find you back on GitHub. You can choose an emoji to accompany your status by clicking on the face icon next to the status message input.

    5. Check the “Busy” box, so that other users will receive a notification from GitHub about your status when they mention you in issues and pull requests, assign you to an issue, or request a review from you.

    6. You can also set a status on Slack. The process is very similar to GitHub’s, i.e. you should log in, click on your profile picture at the top-right of the window, and select “Update your status”. That will open a pop-up where you can write a status message.

  2. Inform your co-Maintainers:

    1. Send them an email or a direct message on Slack.

    2. If you need help finding contact information for any of your fellow Maintainers, contact the Maintainer Community Lead.

Resources#

Maintainer Onboarding Curriculum#

The curriculum used at Maintainer Onboarding. This resource can be a helpful reference for Maintainers after they have completed onboarding. It includes tips for managing issues on a repository, guidance for tagging the Curriculum Team on issues and pull requests, and plenty of other useful information you might want to return to after onboarding.

Introduction to The Carpentries Workbench#

Documentation for The Carpentries Workbench, open source infrastructure for lesson websites. The documentation explains how to install the Workbench so that Lesson Maintainers can edit and preview their lessons on their own computer, how to initialise a new lesson and use the various elements of the lesson template, and how to keep up to date with the latest changes to the infrastructure.

Curriculum Advisory Committee Consultation Rubric#

This rubric defines the division of responsibilities between The Carpentries Maintainers and The Carpentries Curriculum Advisory Committees (CACs). It can be used by Maintainers to help determine whether to notify or ask the relevant CAC about a proposed change to their lesson.

Curriculum Development Handbook#

A guide to the lesson design process recommended by The Carpentries. The CDH provides details of the curriculum structure used by our Lesson Programs, the vocabulary we use to describe the life cycle stages of the lesson, and the steps we encourage Lesson Maintainers to take through those stages. Note: the Curriculum Team is in the process of replacing the content of the CDH with this handbook andthe Collaborative Lesson Development Training curriculum, and it is no longer actively updated.

Collaborative Lesson Development Training Curriculum#

A lesson designed to teach skills and good practices in lesson design, lesson website development, and collaboration via GitHub. Community members can apply to join this training, and/or follow the curriculum in their own time.

FAQ#

List of frequently asked questions relevant to the content in the handbook.

Question 1

Response 1

Question 2

Response 2

About This Handbook#

This handbook is designed to support Maintainers - members of The Carpentries community who maintain one or more lesson repositories for our lesson programs. It is maintained by The Carpentries Curriculum Team. If you believe anything needs to be added or updated here, or if you would like to provide feedback on the content, please send an message to the Curriculum Team or open an issue on the source repository of this handbook.