Maintainer Guidelines

The Carpentries Maintainers work with the community to make sure that lessons stay up-to-date, accurate, functional and cohesive. They monitor their lesson repository, make sure that PRs 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.

The division of responsibilities between Maintainers and Curriculum Advisors is detailed in this consultation rubric.

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.

How to Stay in Touch

The overall Maintainer community communicates using our mailing list and our Slack channel. If you do not already have a Slack account with The Carpentries, you can create one.

The Maintainer community meets monthly to discuss issues relevant to all lesson Maintainers. Our meeting schedule can be found on our CodiMD and on the community calendar.

Each Lesson Team also has their own Slack channel. A link to join your lesson’s Slack channel can be found in the README file in your lesson repository.

How to Handle Issues

The Maintainer Onboarding curriculum contains some guidelines for how to respond to community-submitted issues.

Spam and Bots

The Maintainer Onboarding curriculum also contains guidance on how to handle contributions you judge to be spam and/or made by automated/semi-automated GitHub accounts.

How to Get Help

There are many ways to request help on an issue or PR you are reviewing. To get help from other Maintainers or the general community, use the help wanted or good first issue labels. If your lesson is included on the Help Wanted page of The Carpentries website, issues labelled help wanted will automatically be listed for potential contributors to find there.

If an issue affects the overall structure or scope of the lesson, you can refer the issue to your curriculum’s Curriculum Advisory Subcommittee by assigning it to the appropriate CAC GitHub team. Curriculum Advisors meet approximately quarterly.

You can also get help from other Maintainers and interested community members by posting a question to your lesson’s Slack channel.

Maintainer Onboarding

The process for Maintainer Onboarding is currently on hold. If you are interested in becoming a lesson Maintainer, please contact us at team@carpentries.org.

New Maintainers go through an onboarding process, led by a member of The Carpentries Curriculum Team and the Maintainer Community Lead. Unless otherwise specified in the workflow below, the duties below are divided ad hoc between Curriculum Team member and Maintainer Community Lead.

The curriculum for onboarding new Maintainers is available as a Maintainer Onboarding Lesson. This documentation describes how to recruit new Maintainers and take them through the onboarding process.

Note to Core Team members: the workflow below is also available as a Asana project template. Once you’ve created your project, share it with the Maintainer Community Lead.

  1. Identify lessons in need of additional maintenance support. This includes surveying current Maintainers using a Google form.

  2. Create a copy of the Maintainer Onboarding recruitment form and adjust templated text as needed.

  3. Create a blog post to announce opening of applications. (Example blog post.) Submit blog post text to the Communications Manager.

  4. Coordinate with Communications Manager about announcing on other channels (e.g. newsletter, Twitter).

  5. Once the application period has closed, review applications and determine who to invite.

  6. Determine appropriate schedule for Maintainer Onboarding sessions based on responses to the scheduling poll included in the application.

  7. Send accepted applicants an invitation to become a Maintainer. Send non-selected applicants a rejection email.

  8. Create a private Slack channel (Maintainer-Onboarding) and invite trainees.

  9. Populate the Maintainer Onboarding Etherpad with meeting dates and times. Use timeanddate meeting time announcer links to make it easy for people to convert meeting times to their own time zone.

  10. Create calendar invites with Zoom room and Etherpad link and send to trainees.

  11. Set up a new event in AMY with the slug YEAR-MO-DA-maintainer-onboarding. Add trainees as learners. Add onboarding leader (Curriculum Team member and/or Maintainer Community Lead) as instructor.

  12. Decide on lesson assignments and send lesson assignment email.

  13. One week before the first onboarding meeting, send a reminder email.

  14. Run onboarding according to the curriculum. Keep record of who participates.

After onboarding:

  1. Send congratulations email to new Maintainers.

  2. Add new Maintainer to the appropriate team for Software Carpentry, Data Carpentry, Library Carpentry, or The Carpentries Lesson Maintainers. This will give them write privileges for that lesson’s repo.

  3. Add to lessons table on appropriate Lesson Program lesson page (e.g. https://datacarpentry.org/lessons).

  4. Award them a Maintainer badge in AMY. If the individual has consented to having their profile published, they will appear on The Carpentries Maintainers page within a day.

  5. Add them to the “maintainers” channel in the Carpentries Slack.

  6. Add them to the “maintainers” Topicbox email list.

  7. Send introductory emails for each new Maintainer(s) to the existing Maintainers for their lesson.

  8. Send email to the Maintainers email list announcing new Maintainers.

  9. Run sendmail_maintainer_certificates.R to send new Maintainers their certificates.

  10. Publish a blog post welcoming new Maintainers (example blog post here.

  11. Coordinate with the Communications Manager to announce new Maintainers in the next newsletter, on Twitter, and Slack general channel.

  12. Clear member list on the Maintainer-Onboarding TopicBox.

  13. Archive the Asana project.

Maintainer Community Meetings

The Maintainer community meets on the third Wednesday of every month. Times for these meetings can be found on the Community Calendar. A reminder for these meetings should be sent out to the Maintainers email list one week before the meeting takes place, and the Maintainers Etherpad should also be updated. Ideally, these meetings will be co-facilitated by a member of The Carpentries Core Team and the Maintainer Community Development Lead.

The following is a Etherpad template that can be used as a Maintainer meeting agenda:

Join from PC, Mac, Linux, iOS or Android: {Zoom link}

Meeting 1: Wednesday, {Date} at 16:00 UTC
Please click this link to convert to your local time: (add time converter link using [TimeandDate's Event Time Announcer](https://www.timeanddate.com/worldclock/fixedform.html))

Meeting 2: Wednesday, {Date} at 21:00 UTC
Please click this link to convert to your local time: (add time converter link using [TimeandDate's Event Time Announcer](https://www.timeanddate.com/worldclock/fixedform.html))

Attending (1st Meeting):

- {name}
- {name}

Attending (2nd Meeting):

- {name}
- {name}

Timekeeper:
Notetaker (please add notes within agenda below):

Agenda:

- Introductions (5 min)
- Updates from Carpentries team (10 min):
 - Topic 1
 - Topic 2
- Current Maintainer RFCs: https://github.com/carpentries/maintainer-RFCs/issues (10 min)
- Quarterly Software Review (item owned by Lesson Infrastructure Technology Developer) (5 min)
- Lesson issues to discuss (please add links to the issues you would like feedback or insight on) (30 min):
 - Issue 1: {link}