Content from Welcome to the Maintainer Community

Last updated on 2023-03-17 | Edit this page

Overview

Questions

  • What does it mean to be a Carpentries Maintainer?
  • What is my motivation for becoming a Maintainer?
  • What should I expect from this training?

Objectives

  • Introduce yourself to your fellow new Maintainers.
  • Describe what will and will not be covered in this training.
  • Articulate The Carpentries overall goals for our Maintainer community.

Pronouns and Names

Using correct names and pronouns is important to setting a tone of respect. Learning these is hard to do quickly, so we recommend displaying it prominently during the training.

If on Zoom, give everyone a moment to update their display name to reflect this information.

If in person, encourage attendees to put this information on worn name tags or table-displayed name placards.

Note that pronouns are personal and some participants might prefer not to share them. Do not force people to share their pronouns.

Before The Course Begins

Sign In

Ask participants to sign in with their name, pronouns, institution, lesson assigned, and potentially a short icebreaker question (“Tell us one good thing that happened in the past week.”) in the course’s shared notes.

Code of Conduct

To make clear what is expected, everyone participating in The Carpentries activities is required to conform to our Code of Conduct. This Code of Conduct applies to all spaces managed by The Carpentries including, but not limited to workshops, email lists, online forums and on GitHub. Please review the Code of Conduct to familiarise yourself with it.

Introductions

Hello everyone, and welcome to The Carpentries Maintainer Onboarding. We are very pleased to have you with us.

Introductions

Ask participants to introduce themselves verbally with the same information as in sign-in.

Previous Experience (5 min)

Please put an “x” next to each item that corresponds to your answer to the question

In what ways have you been involved in The Carpentries community?

  • Contributed to lesson materials
  • Helper
  • Instructor
  • Learner
  • Trainer
  • Executive Council member
  • Committee or Task Force member
  • Workshop organizer or host
  • None of the above

How often do you currently use Git?

  • Never
  • Less than once per year
  • Several times per year
  • Monthly
  • Weekly
  • Daily

How often do you currently use GitHub?

  • Never
  • Less than once per year
  • Several times per year
  • Monthly
  • Weekly
  • Daily

Which operating system(s) do you commonly use?

  • macOS
  • Linux
  • Windows
  • Not sure

We have a range of folks with different levels of previous experience with The Carpentries and different types of technical background. We are not all experts in Git or any other specific software. That is ok! You will learn some of the specific things you need to interact with The Carpentries lessons on GitHub during this training and get information about how to continue learning and growing in this role.

Maintainer Onboarding Overview

The goal of this training is to provide you with the skills and information you need to become a Carpentries Maintainer. During this training, we will:

  • Orient you to The Carpentries goals and vision for lesson maintanence
  • Help you get connected with other Maintainers and the overall Maintainer community
  • Develop skills for creating a positive environment for all contributors
  • Become familiar with the key components of the lesson template
  • Practice core technical skills for lesson maintanence
  • Learn how and when to elevate issues to your Curriculum Advisory Committee

What This Onboarding Does Not Cover

The Carpentries supports over 40 official lessons across our three Lesson Programs (Data Carpentry, Library Carpentry, and Software Carpentry). At any given time, there are also dozens of community-supported lessons in active development in The Carpentries Incubator. This training is intended for Maintainers of official lessons, and we will not cover how new lessons are developed, vetted, and adopted into The Carpentries core lesson stack. Those interested in curriculum development are encouraged to read The Carpentries Curriculum Development Handbook. Limited opportunities for training in collaborative lesson development may also be available - read this blog post for opportunities in June and July 2022.

We do not expect you to be an expert in Git or GitHub, or even to have used these tools at all in the past. We will provide you with an introduction to the core skills you need to respond to uncomplicated issues and pull requests, however, there will undoubtedly be more complicated maintenance situations that require Git skills beyond what we will cover in this training. The best way to learn Git is to work with it, and we encourage you to reach out to your co-Maintainers and others in the Maintainer community for support and resources. We have regular co-working sessions where you can bring questions to the group, and also provide each other support in asynchronous communication channels. We’ll introduce those channels momentarily. The Software Carpentry Git Novice lesson and the Library Carpentry Introduction to Git lesson are also great resources for learning and reviewing the basics you will need to maintain your lesson.

Goals for Lesson Maintenance

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, and we will talk about how we do that later, 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 that you:

  • Monitor your 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. They aren’t perfect!
  • 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.

Maintainer Guidelines

You can find more details about Maintainer Guidelines in The Carpentries documentation.

Motivation (5 minutes)

Why are you becoming a Maintainer? What goals do you have for this training?

Next, we will explore in more detail who contributes to The Carpentries lessons, what kinds of contributions you can expect to receive, and how to apply The Carpentries Core Values to communicating with contributors.

Key Points

  • The Carpentries is a community of practice. We strive to provide a welcoming environment for all learners and take our Code of Conduct seriously.
  • This training will prepare you to get started in your role as a Maintainer.

Content from Communicating with Contributors

Last updated on 2023-03-17 | Edit this page

Interacting with Contributors

Overview

Questions

  • What types of contributions am I likely to encounter and how should I handle them?
  • How do I make sure contributors feel valued, even if their contribution is not accepted?
  • How can I direct contributors’ energy to where it will be most useful?

Objectives

  • Use The Carpentries Core Values to guide your interactions with contributors.
  • Gain confidence identifying and politely declining out-of-scope contributions.
  • Develop strategies to avoid demotivating 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:

  • Answer quickly
  • Be kind and make newcomers feel part of the team
  • Set expectations and needs early
  • Point newcomers to easy tasks
  • Keep the issue list clean and triaged
  • Dismiss or identify outdated information
  • Create a live FAQ section

How Are We Doing? (5 minutes)

How do you feel The Carpentries community does overall in meeting these recommendations? Are there particular areas of strength or places where there is room for improvement?

Where do Contributions Come From?

While anyone can contribute to The Carpentries lessons, the vast majority of contributions come from:

  • Trainees who have gone through Instructor Training and are submitting a contribution as part of “checkout” to complete their Instructor certification.
  • Workshop Instructors (and helpers) who have recently participated in a workshop and noticed difficulties with the materials.

Everyone who goes through The Carpentries Instructor Training program is required to contribute to a Carpentries lesson (or other resource) in order to become certified. We train over a thousand people each year to be Instructors, about half of whom complete the certification process. A large proportion of the contributions you will receive come from Instructor trainees.

During Instructor Training, we strongly encourage contributors to contribute to discussion on existing PRs and issues, to submit a PR to resolve an issue that the Maintainers have marked “help wanted”, or to submit issues describing bugs or difficulties in teaching the lesson.

Keeping your repository’s “help wanted” list up-to-date is a great way to maximize useful contributions. The Carpentries website compiles a list of all issues marked with the “help wanted” tag across all of our official lessons. Contributors can search this list to find places where Maintainers have specifically requested help, making it more likely that their contribution will be useful and accepted.

Help Wanted (5 minutes)

Locate your lesson’s help wanted list.

  • How many issues are currently open with that tag? How many have been closed?
  • Is it clear what action is desired (ie what help is wanted?) for each issue marked help wanted?
  • Are there any old issues that are out of date and are still marked help wanted?
  • Are there any new issues that should have the help wanted tag and don’t?

Spending some time cleaning up your lesson’s help wanted list in your first few months as Maintainer will save you and your co-Maintainers time in the long term and help ensure higher-quality contributions.

Despite our best efforts in encouraging the types of contributions listed above, you will also receive unwanted or unhelpful contributions, including:

  • addition of new material covering topics outside of the scope of the lesson;
  • changes to the way a topic is presented that are inconsistent with The Carpentries pedagogical model;
  • changes to the technology taught in the lesson (e.g. introduction of a new plotting system);
  • multiple unrelated suggestions.

These contributions may come in the form of an issue or a PR. 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 on “Best Practices for Maintainers” includes a section on “learning to say no”. They recommend that you:

  • Thank them for their contribution.
  • Explain why it doesn’t fit into the scope of the project, and offer clear suggestions for improvement, if you’re able. Be kind, but firm.
  • Link to relevant documentation, if you have it. If you notice repeated requests for things you don’t want to accept, add them into your documentation to avoid repeating yourself.
  • Close the request.

Content based on github.com/github/opensource.guide used under the CC-BY-4.0 license.

Practice Saying No (10 minutes)

Choose one of the open issues linked below. Compose a 2-3 sentence response that follows the guidelines above. Add your response to the Etherpad.

Motivating Language (5 minutes)

We teach Instructors to avoid using language that can demotivate learners. The same principles apply in lesson maintenance. What are some words or phrases that could have the effect of demotivating contributors? What alternatives can we use to express this meaning in a positive and motivational way?

In the Etherpad, make a list of demotivating words/phrases and alternatives.

Checkout Contributions by Email

We allow trainees to submit feedback and suggested changes to Data Carpentry and Library Carpentry lessons via email, as one part of their checkout.

These emails are handled by a member of the Core Team, who will then open an Issue on the lesson repository on behalf of the trainee. The Core Team will not be able to follow up on these Issues, e.g. by opening a Pull Request or replying to the thread with more information. All such Issues will include a brief introductory statement to distinguish them from contributions made directly via GitHub. See an example of a contribution submitted by email.

Top Ten Tips for Managing Issues and PRs

  1. Acknowledge receipt - Even if you won’t be able to take action on an issue/PR immediately, send the contributor a quick message to let them know you received and appreciate their contribution. Always say thank you!
  2. Tag issues with descriptive labels - For community-submitted issues, remember to add appropriate labels, even if you are not going to immediately take action. This shows contributors that issues are being paid attention to and encourages others to take action on issues.
  3. Include appropriate cross-references - When putting in a PR to address an existing Issue, include a link to the Issue. GitHub will automatically add a note to the Issue linking back to the PR. This is also good practice when communicating in conversation threads on related Issues and PRs.
  4. Use the @ symbol to tag people in a conversation - Most people don’t subscribe to all of The Carpentries repositories (there are a lot!) and will only get email alerts if their GitHub handle is tagged. This is a good way to make sure relevant people are included in the conversation. You can also use @ to tag your Curriculum Advisory Committee. More on that later.
  5. Request reviews for non-trivial changes. You can request a review from a fellow Maintainer or from someone else who has been active on the repository. This is another way of including relevant people in the decision-making process.
  6. Don’t merge your own PRs - Even for small PRs, it’s a good idea to have a second person check for typos and formatting issues. In general, always get a second opinion before merging your own PR. This is a good time to request a review.
  7. Do edit PRs as needed - It is OK to directly edit a contributor’s PR if there are minor issues preventing it from being accepted. Many of our contributors are non-responsive to requests to update a PR. This is OK. If the contribution is important - make the minor changes and merge.
  8. Don’t close an issue or PR without explaining why - Except in the (very rare) case of spammy contributions, take a moment to acknowledge the contribution and explain why it won’t be incorporated.
  9. Do close issues that have gone stale, are outdated, or out of scope (after explaining why).
  10. Pay attention to comments about accessibility and demotivating or exclusionary language.

How to Label Issues

To find a list of issue labels, their corresponding meanings, and when to use each, take a look at this guide on How to label issues in The Carpentries handbook.

Key Points

  • Valuing all contributions is one of The Carpentries Core Values.
  • Not all contributions can, or should, be accepted.

Content from Communicating with Other Maintainers

Last updated on 2023-03-17 | Edit this page

Synchronous communications

Overview

Questions

  • How do I get in touch with other Maintainers?
  • What resources exist for supporting me in this role?

Objectives

  • Join the appropriate communication channels to stay connected with fellow Maintainers.
  • Know how to get in touch with others in The Carpentries who support Maintainers.
  • Add Maintainer meetings to your calendar.

There are two opportunities to connect with the overall Maintainer team each month.

Maintainer meetings

We meet virtually on the third Wednesday of each month at two different time slots. We will take time together to add these meetings to your calendar in a moment.

Our monthly Maintainer meetings are an excellent place to connect with the broader Maintainer community, engage in discussions around topics of interest to Maintainers (including open Requests for Comment (RFCs)), and stay informed about upcoming work by other parts of The Carpentries community that may impact lesson maintenance.

We recognize that not everyone can attend these monthly meetings, and so also communicate important information through our main TopicBox and Slack channels. So don’t worry if you can’t attend! We do strongly encourage joining from time to time, though, as it’s a good way to get to know other Maintainers.

Maintainer co-working corrals

On the first Wednesday of each month, we get together for a co-working session. This is a good time to get input from other Maintainers, and from the Maintainer Community Lead, on difficult or tricky issues. Co-working with Maintainers on other lessons also provides you with a broader overall vision of The Carpentries curriculum stack. It’s a great opportunity to engage in lateral knowledge transfer and community learning!

Any Maintainer can add an issue or PR to the co-working corral agenda by adding it to the CodiMD pad. It is also perfectly fine to join the meetings without a specific issue already selected to work on. You do not need to attend the monthly Maintainer meetings to join the co-working corrals, and vice versa. All Maintainers are welcome!

Add to Your Calendar (5 minutes)

Add the monthly Maintainer meetings and co-working corrals to your calendar by either

  • subscribing to The Carpentries community calendar and copying events to your Google Calendar, or
  • clicking the TimeandDate links on the Maintainers CodiMD pad to convert the events to your local time, and adding to your calendar manually.

If you are planning to attend the upcoming meeting, add your name to the CodiMD pad to let us know you will be there!

In addition to these monthly opportunities to connect across the broad Maintainer community, you are encouraged to set up regular check-ins with the co-Maintainers for your lesson. The next section will provide more information about how to stay in touch with both the overall Maintainer community and your co-Maintainers.

Asynchronous communications

Because we are a globally distributed group, the vast majority of our work is done asynchronously. There are three primary asynchronous communication channels shared across the Maintainer team.

TopicBox

The Maintainers TopicBox list is used primarily for announcements relevant to the full Maintainer team, including reminders about upcoming meetings. Posts from individual Maintainers asking questions or introducing topics for discussion are extremely welcome, but our Slack channel does seem to be a more active place for back-and-forth discussion.

A few lists exist around specific curricula (search for lists starting with curriculum, but most have not been very active. If you would like to have a public TopicBox list created for discussions of your lesson, or a private list for your Maintainer team, please let us know.

Slack

To be added to our private Maintainers channel on Slack, you will need to join The Carpentries organisation. Our general Maintainers channel is a good place to ask questions of the full Maintainer team, or request input on specific issues and PRs. Most curricula also have a public Slack channel for discussing issues with the community (browse for channels starting with dc, lc, or swc). Specific curriculum channels have not historically been very active, but we encourage any efforts to increase interaction with the community on these channels. You can also use curriculum-specific channels for communicating with your co-Maintainers, or you can create a private channel for yourself and your co-Maintainers. If you would like a private channel to be created for you, please let us know.

GitHub

The majority of day-to-day interactions with your co-Maintainers will be on GitHub. You will need to be subscribed to (“watching”) your lesson repository to get email alerts about new issues, PRs, and other activity on your lesson. You can @ mention an individual Maintainer, your lesson team, and / or your Curriculum Advisory Committee to ensure that the appropriate person sees your message. Feel free also to @ The Carpentries Curriculum Team (Toby Hodges, Erin Becker, François Michonneau, Zhian Kamvar, Michael Culshaw-Maurer) using @staff-curriculum and the Maintainer Community Lead (@vinisalazar).

Tagging in your Lesson Team

Each group of Maintainers is associated with a GitHub team. You can find the name of your team below:

What is your lesson team’s name? (3 minutes)

Find your lesson team’s name and add it to the Etherpad.

Tagging in the Curriculum Team

To tag in the curriculum team on any repository hosted in one of the official lesson program GitHub organisations (Data Carpentry, Library Carpentry, Software Carpentry), use @staff-curriculum. On The Carpentries GitHub org, the team name is @core-team-curriculum. We are working on reconciling team names across GitHub organisations.

We also highly recommend subscribing to the Maintainer RFC (request for comments) repository. This repository is the primary platform for discussion and feedback from the Maintainer community on issues affecting Maintainers as a whole. We try to remember to announce new RFCs on TopicBox and Slack, but staying subscribed here will allow you to see others’ comments as they come in. To leave your feedback on an existing RFC, go to Issues and leave a comment. We also discuss RFCs at monthly Maintainer meetings to allow for a more nuanced back-and-forth conversation.

General Carpentries News

Subscribing to these channels will ensure you are up to date on issues affecting your lesson and lesson maintenance in general. To have a broader overview of all the exciting activity going on in The Carpentries community, we recommend subscribing to one or more of the following channels:

If you would really like to keep up to date on everything that is happening, The Carpentries maintains a variety of mailing lists on TopicBox and over 100 Slack channels, including spaces dedicated to discussion of particular curricula, connecting local and regional groups, and job opportunities.

Subscribe! (5 minutes)

That’s a lot of communication channels! You don’t need to subscribe to everything. The list below summarizes which channels are required and which are highly recommended.

Required

Highly Recommended

Take a few minutes to subscribe to the above channels. Write “done” in the Etherpad.

Introduce Yourself (2 minutes)

While folks are working on subscribing to the channels above, I will add you to the private Maintainers Slack channel. Please introduce yourself on that channel, including what lesson you will be maintaining.

Maintainer Capacity

Signing on as a Maintainer is not a lifelong commitment! The Carpentries recognises that this is a volunteer role and is committed to supporting your mental and emotional health. You are always free to step down from the Maintainer role, either permanently or to take a break. If you plan to take a short break (a couple of weeks), please let your co-Maintainers know. For longer breaks (a few months or longer), or if you would like to step down permanently, please notify the Curriculum Team by emailing team@carpentries.org so we can find someone else to support the lesson.

This also applies in reverse! If you are not able to get in touch with at least one other Maintainer for your lesson, please get in touch with the Curriculum Team. We may need to find more Maintainers to support the lesson.

Key Points

  • The Maintainer community communicates on TopicBox, Slack, and GitHub.
  • There are two opportunities to connect synchronously each month - a co-working session and a general meeting.

Content from Infrastructure for Lesson Maintenance

Last updated on 2023-03-17 | Edit this page

Maintainers and Forked Repositories

Overview

Questions

  • How do I review pull requests?
  • How do I make changes to pull requests?
  • How do I accept pull requests?
  • What should I know about how the lessons are formatted?

Objectives

  • Understand the structure of the lesson source repository—know which elements generate the various parts of the lesson page.
  • Navigate to the correct file and element to update each section—including instructor notes, setup, questions, timings, learning objectives, key points, and glossary.
  • Be familiar with the various callout boxes used in Carpentries lessons and be able to use them appropriately.

If this is the first time you are maintaining a project where you and other people are going to be submitting changes there are two perspectives you need to keep in mind: one of the “maintainer” and one of the “contributor”.

  • Maintainers: can directly push code to the repository
  • Contributors: cannot directly push code to the repository, and need to create a separate fork
Diagram illustrating workflows for pushing and pulling to a remote for Maintainers and contributors.

Pushing and pulling directly to the remote repository owned by The Carpentries

The Software Carpentry Git lesson and Library Carpentry Git lesson show you how you can interact with a repository from an owner and Maintainer point of view because you are allowed to push directly to your project on GitHub (see label 1 in the above diagram).

As a Maintainer to one of our lessons, you will be able to interact with the lesson just like it was your own repository (see label 1 in the above diagram). The only difference is the account the repository is under. So instead of username/repo it will be something like carpentries/repo. This means when you get the git clone url, you will have to get it from the carpentries/repo location, not your own.

In this setup, since you are cloneing down from the original carpentries repo, the remote will be your origin. This is the same workflow as if you are working on your own personal repository, and you can git push origin gh-pages.

An alternative workflow: Pushing and pulling to a remote (fork)

Some Maintainers choose to work using the forking model of collaboration. Even though they have access to the original “upstream” Carpentries repository, they will make a “fork” of The Carpentries repository so they have a copy (i.e., fork) in their own account (see label 2 in the above diagram). Using this workflow gives you (the Maintainer) the same workflow as any other contributor to your lesson (since contributors will also need to work on a fork).

Forking a Repository

To fork a repository on GitHub, you can visit a repository and add /fork at the end of the URL or you can click the “fork” button in the top right:

Screenshot of the top bar of swcarpentry/git-novice with four buttons on the top right: sponsor,watch, fork, and star

Once you fork the repository, there will be the original “upstream” carpentries/repo and your own “fork”, username/repo (see label 2). When you visit your fork on the GitHub website, you will see a grey toolbar above the file list that says “This branch is up to date with carpentries/repo:branch.”

Screenshot of grey box above a file list on github that says "This branch is up to date with swcarpentry/git-novice:gh-pages." It has two buttons, one labelled "Contribute" and the other labelled "Fetch Upstream"

You can clone your username/repo down to your computer like any other repository you want to work on locally and push and pull your changes to your remote (label 3). Because the repository you cloned from is your own “fork” (username/repo), the version in your account that you cloned from is the “origin” repository (see the blue colored “origin” label in the diagram). You can then issue a pull request (PR) to the original carpentries/repo repository (see label 4).

For PRs from non-maintainers you will review these changes and ask for changes if needed. As the Maintainer, you can review and/or accept these PRs (including your own) because as a Maintainer you will have the repository permissions (in carpentries/repo) to accept the PR (see label 5).

Keeping your fork up-to-date

As more changes come in from other contributors and accepted by you or other Maintainers, the forked repository (bottom right) and your own local copy (bottom left) will be out of sync. This time, when you visit your fork on GitHub, you will see that GitHub will show you that your branch is N commits behind the upstream repository. You can use the “Fetch upstream” button to bring those changes to your own repository. Screenshot of grey box above a file list on github that says "This branch is 2 commits behindwith swcarpentry/git-novice:gh-pages." It has two buttons, one labelled "Contribute" and the otherlabelled "Fetch Upstream". The "Fetch upstream" button has been clicked to reveal a menu that says"Fetch and merge 2 upstream commits from swcarpentry:gh-pages" with subtext that says "Keep yourfork up-to-date-with the upstream repository" and a link that says "Learn More" There is a white"compare" button and a green "fetch and merge" button displayed

If you wanted to perform this update locally, you would set the carpentries/repo as a new remote called “upstream” and then pull the changes from upstream.

We will now practice using the recommended workflow for pushing and pulling to a remote.

You will be assigned to a breakout group of 2-3 people. Once you are in breakout rooms, decide who will play the role of the Maintainer (“M”), and who will be the contributor (“C”).

Working on the gh-pages branch (10 minutes)

  1. M: Create a repository: <date>-collab-example and initialise it with a README.md file so the repository is not completely empty.
  2. M: Add C as a collaborator under the repository settings.
  3. C: Accept the collaboration invitation (check your e-mail)
  4. M + C: clone the repository to your local machine
  5. M + C: Both add your name to the README.md file
  6. M + C: add and commit your changes
  7. M + C: push your changes to the remote
  8. M + C: someone will have a merge conflict

Working on a new branch (15 minutes)

  1. Make sure that your local version is up-to-date: git pull origin gh-pages
  2. Create a new branch: git checkout -b BRANCH_NAME or git switch -c BRANCH_NAME
  3. Make changes, add, commit, and push the changes
  4. Create a PR

Working on the gh-pages branch

  1. C: fork the repository from M
  2. C: clone from your respitory (c/<date>-collab-example)
  3. M + C: Both add your name to the README.md file
  4. M + C: add and commit your changes
  5. M + C: push your changes to the remote (C: it will be your origin)
  6. C: Issue the PR
  7. M: Review and merge the PR
  8. C: Setup the upstream remote
  9. C: Sync the upstream changes to your local machine and your fork

Repeat but using a branch

  1. Make sure that your local version is up-to-date: git pull origin gh-pages
  2. Create a new branch: git checkout -b BRANCH_NAME or git switch -c BRANCH_NAME
  3. Make changes, add, commit, and push the changes
  4. Create a PR
  5. M: Review and merge the PR
  6. C: Setup the upstream remote
  7. C: Sync the upstream changes to your local machine and your fork

Questions and Answers (5 minutes)

Please add questions to the Etherpad.

The Carpentries Lesson Infrastructure

The infrastructure for Carpentries lessons is managed through the styles repository, and documented on the lesson-example repository.

New Infrastructure Coming!

We are in the beta testing phase for The Carpentries Workbench that is designed to be more user friendly for both contributors and Maintainers. All lessons will transition to using the workbench in January 2023.

Who Maintains the Lesson Infrastructure?

Up until March 2020, the lesson infrastructure was maintained by the Lesson Infrastructure Committee. The activity of the Committee was put on hold during the COVID-19 pandemic and we are making concious strategic decisions about how to reform this committee ahead of January 2023.

The Lesson Infrastructure is officially maintained by the Curriculum Team, with the help of Maxim Belkin.

Lesson homepage

The lesson homepage is built from the index.md file and provides an overview of the lesson, including any prerequisites, an introduction to the dataset used, a schedule showing the episodes and the time allotted for each, and any other information learners will need for the lesson.

The schedule will automatically be included in the lesson homepage based on information present in the episode files.

Episode files

The majority of a lessons content is in its episode files. Episode files are stored in the _episodes/ folder within your lesson repo (or in _episodes_rmd/ for lessons written in R). Episode file names must start with a two-digit identifier number (e.g. 01) followed by a short descriptive name, separated by a dash (-). For example 02-loop.md, 03-lists.md. The numeric identifier is used to place your episode files in the correct sequence within the lesson. Episode files are written in Markdown or RMarkdown.

Episode headers

Each episode starts with a YAML header that looks something like this:

---
title: "What is the shell?"
teaching: 5
exercises: 0
questions:
- "What is the shell?"
- "What is the command line?"
- "Why should I use it?"
objectives:
- "Describe the basics of the Unix shell"
- "Explain why and how to use the command line"
keypoints:
- "The shell is powerful"
- "The shell can be used to copy, move, and combine multiple files"
---

The information stored in the YAML header is used by the lesson infrastructure to populate important parts of the lesson webpage.

For example, “questions” are scraped from each episode file and added to the schedule on the lesson homepage.

Scavenger Hunt (5 minutes)

Identify the file and lines of the file that control the following output for your lesson. Add the file name and copy the relevant lines to the Etherpad.

  • Questions (for episode 1)
  • Timings (for episode 1)
  • Learning objectives (for episode 1)
  • Key points (for episode 1)
  • Instructor notes
  • Setup instructions
  • Glossary

For a step-by-step guide to how the lessons are structured, and what syntax to use to add code chunks, exercises, and other elements, please read the technological introductions chapter of The Carpentries Curriculum Development Handbook.

For a more in-depth guide, read through the lesson example.

Key Points

  • Make a branch to create a pull request.
  • The Carpentries lessons share a consistent style, which is controlled by styles and documented in the lesson-example

Content from Communicating with Curriculum Advisors

Last updated on 2023-03-17 | Edit this page

Your lesson is part of an overall curriculum within a Lesson Program. For example the Project Organization and Management for Genomics lesson is part of the Genomics curriculum, which is part of the Data Carpentry Lesson Program. Data Carpentry has several curricula, while Library Carpentry and Software Carpentry each have a single curriculum.

Overview

Questions

  • How does my lesson fit into the overall curriculum?
  • What kinds of changes do I have the authority to make?
  • Who should I talk to about larger-scale changes?

Objectives

  • Describe who has authority, and responsibility, to make different types of decisions.
  • Gain confidence in merging simple PRs independently.
  • Know when and how to contact Curriculum Advisors.

The work that Maintainers do on routine upkeep of the lessons is complimented by the Curriculum Advisory Committee (CAC) for each curriculum. Curriculum Advisors provide high-level oversight, vision, and leadership for a curriculum and guide large-scale updates.

The CAC Consultation Rubric outlines the division of responsibilities for Maintainers and Curriculum Advisors, including

  • issues over which Maintainers have full authority and which do not need CAC involvement,
  • issues about which Maintainers should consult the CAC,
  • issues that may benefit from Maintainers consulting with the CAC, but over which Maintainers retain authority, and
  • issues for which Maintainers must seek CAC approval.

Curriculum Advisory Committees exist for the following curricula:

  • Data Carpentry Astronomy
  • Data Carpentry Geospatial
  • Data Carpentry Genomics
  • Library Carpentry
  • Software Carpentry

In mid-2022, we will be recruiting Curriculum Advisors for the following curricula:

  • Data Carpentry Ecology
  • Data Carpentry Social Sciences
  • Data Carpentry Image Processing

Each CAC includes at least one Maintainer, and we encourage you to apply for your curriculum’s CAC when applications open.

Urgent Issues

If any urgent issues arise which would normally be under the authority of the CAC, and the CAC for your curriculum has not yet convened, please contact the Curriculum Team for support and assistance.

You can tag in your Curriculum Advisory Committee on an issue in your lesson repository using their team name (e.g. “@datacarpentry/curriculum-advisors-astronomy” or “@LibraryCarpentry/curriculum-advisors”). The CAC chair is responsible for watching the repository and serving as a liaison with the curriculum’s Maintainers. Each Curriculum Advisory Committee also has a public TopicBox list, where Maintainers and other community members can bring issues for consideration. More information about each CAC, including mailing list and GitHub repositories, is available on the Curriculum Advisors homepage.

Which strategy? (5 minutes)

Match the issue with the correct strategy for resolving it.

  1. Needs elevation to CAC
  2. Simple fix by a single Maintainer without review
  3. Put in a PR and wait for another Maintainer to review
  4. Raise the issue for conversation at Maintainer co-working corral or on email list

Key Points

  • The Curriculum Advisory Committee consultation rubric outlines division of responsibilities between Maintainers and Curriculum Advisors.