Content from Welcome to the Maintainer Community

Last updated on 2024-03-11 | Edit this page

Estimated time: 15 minutes

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.

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

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.

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 maintenance
  • 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 maintenance
  • 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. We also offer training in collaborative lesson development.

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 monthly Maintainer meetings where you can bring questions to the group, and also provide each other support in asynchronous communication channels. We’ll introduce those channels later in this onboarding. The Software Carpentry Git Novice lesson and the Library Carpentry Introduction to Git lesson are also great resources for learning and reviewing the core skills 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. The lessons 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.

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 2024-12-02 | Edit this page

Estimated time: 25 minutes

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.

Interacting with 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.

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 get involved in the Carpentries community in order to become certified, and contributing to a lesson is a popular option. We train over a thousand people each year to be Instructors, about half of whom complete the certification process. Many 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 (i.e. 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 (5 minutes)

The issues linked below are good examples of Maintainers saying “no” politely. Read one of these and reflect on how it uses the recommendations from GitHub’s OpenSource Guide. If you had to respond to this issue, is there anything you would add or do differently?

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.

The Curriculum Team may review and merge pull requests

From time to time, members of The Carpentries Curriculum Team may review and/or merge pull requests opened on your lesson repositories. This might happen because a change is particularly urgent (e.g. it fixes something that is broken in the lesson) or because the change is uncontroversial (e.g. a typo fix or a small improvement to wording, etc) and the Curriculum Team member happens to be looking at the lesson repository at the time. When a member of the Core Team takes this action, it is not because that they expected one of the Maintainers to have handled the contribution sooner. If you disagree with a pull request merged by a member of the Curriculum Team, or want to discuss changes like these with them, please get in touch!

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.

Bots and Spam

Unfortunately, The Carpentries repositories occasionally receive time-wasting contributions, for example containing spurious changes that are not a legitimate attempt to improve the content. (Previously seen examples have included renaming a file for no clear reason and making unnecessary and unhelpful changes to the repository README.) Although we generally encourage you to be thoughtful and to avoid demotivating community members when responding to genuine contributions, you are welcome to close any pull requests and issues that you judge to have been opened in bad faith. If you suspect that a spammy contribution has been made by an automated account (for example using the interaction as a way to train and improve a bot’s model for automation and communication) you may wish to close it without any additional comment that could be used as data for the bot’s training process.

In addition to closing the issue or pull request, please send a short message to The Carpentries team, including the user’s username and a link to the interaction you have concerns about, so that the Technology Team can consider blocking the user from your and other Carpentries repositories.

If you believe it is urgent that action is taken, you may receive a response more quickly by posting to the Maintainers channel on Slack.

As well as closing the pull request or issue and informing The Carpentries team, you might consider taking either or both of the following steps:

  1. Adding the “invalid” label to the issue/pull request
  2. Reporting the issue or pull request to GitHub by clicking ... at the top right of the comment box at the beginning of the conversation thread for the issue/pull request and selecting “Report content”. This will take you to the form for reporting violations of GitHub’s terms of service.

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 2024-02-22 | Edit this page

Estimated time: 10 minutes

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.

Synchronous communications

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.

Add to Your Calendar (5 minutes)

Add the monthly Maintainer meetings 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 is 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 or Erin Becker) using @staff-curriculum and the Maintainer Community Lead (@ndporter).

Tagging in your Lesson Team

Each group of Maintainers is associated with a GitHub team. After you have completed this onboarding, you will be added to the appropriate Maintainer team. You will then be able to find the name of your team below:

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.
  • The Maintainer community meets monthly.

Content from Communicating with Curriculum Advisors

Last updated on 2023-04-18 | Edit this page

Estimated time: 15 minutes

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.

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.

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.

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

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.

Content from Infrastructure for Lesson Maintenance

Last updated on 2024-11-04 | Edit this page

Estimated time: 15 minutes

Overview

Questions

  • 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.

Lesson Infrastructure Transition

This episode will teach you some of the most important elements of The Carpentries lesson infrastructure (the Workbench) that you will need to interact with as a Maintainer. Full documentation can be found on Introduction to The Carpentries Workbench.

What Was “Styles”?

You may come across references to something called “Styles”. Styles is the name for the infrastructure that was used for The Carpentries lessons from 2014 - May 2023. This infrastructure was managed through the styles repository, and documented on the lesson-example repository.

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 re-form this committee ahead of May 2023.

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

Lesson configuration

The global configuration of the lesson - settings that affect the lesson as a whole, such as its title, the “lesson life cycle” stage that may be displayed in the banner at the top of its pages, and the contact information and source repository URL linked in its page footers - are stored in the config.yaml file. This file is in YAML format, containing configuration parameters as key-value pairs. Lesson Maintainers should only need to modify this file very rarely.

Lesson homepage

The lesson homepage provides an overview of the lesson, including any prerequisites, an introduction to the dataset used, and any other information learners will need for the lesson. This content is built from the index.md file in the root folder of the lesson repository.

The Instructor view of the lesson homepage also includes a schedule showing the individual episodes included in the lesson, and the time allotted for each. The schedule is automatically created based on information present in the episode files.

The Learner view of the homepage includes the setup instructions for the lesson: information about the software to install and data to download in order to be ready to follow the lesson. This content is built from the setup.md file in the learners/ folder of the lesson repository (more details later).

Episodes

The majority of a lessons content is in its episode files. Episode files are stored in the episodes/ folder within your lesson repository. Episode files are written in Markdown or RMarkdown. The essential elements of an episode are mentioned below. For complete information about how to construct each element of an episode file, please see the documentation.

Episode headers

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

---
title: "What is the shell?"
teaching: 5
exercises: 0
---

title sets the title of the episode, which will be displayed as a top-level heading on the webpage. teaching and exercises are values (in minutes) indicating how much time the episode is estimated to take to teach, and for learners to complete its exercises. The information stored in the YAML header is used by the lesson infrastructure to populate the schedule.

Fenced Divs

As well as general explanatory content, episodes usually contain a number of blocks of particular types, such as Instructor notes, a list of key points, and exercises and solutions. These blocks of content are formatted to stand out from the other content on the page, and in some cases are treated differently by the lesson infrastructure (e.g. Instructor notes are hidden in the Learner View of the lesson).

These formatted blocks of content are added to episodes (and other pages in the lesson site) as fenced divs: chunks of content delineated (“fenced”) by lines of colon : symbols, with the opening fence accompanied by a tag that defines the class of fenced div being created.

For example, a fenced div belonging to the callout class - used to highlight a particular block of content - can be defined with:

::::::::::::::::::::::::::::::::::::::: callout

Some text here.

:::::::::::::::::::::::::::::::::::::::

Callout

Some text here.

Questions, objectives, and keypoints

Every episode must contain one of each of the following types of fenced div:

  • Questions: Located at the top of the episode file, these are plain language questions that show learners what to expect to gain from the episode. Fenced div class: questions.
  • Objectives: Located at the top of the episode file, objectives are specific goals that learners should be able to accomplish by the end of the episode. Fenced div class: objectives.
  • Keypoints: Located at the end of the episode file, key points are statements of the major take-aways learners should remember from each episode. Fenced div class: keypoints.

Keypoints are automatically gathered from each episode and collected on the “Key Points” page of each lesson. Questions and Objectives are represented in an “Overview” box at the top of each rendered episode page.

Other Fenced Divs

In addition to the callout class shown above, the infrastructure supports several other classes of fenced div that, although not essential, are often included in episodes.

Fenced divs with the tag “challenge” will render as exercises:

::::::::::::::::::::::::::::::::::::::: challenge

This is a challenge.

:::::::::::::::::::::::::::::::::::::::

Challenge

This is a challenge.

Another block with the tag “solution” can be nested inside a challenge to provide the solution to an exercise:

::::::::::::::::::::::::::::::::::::::: challenge

What is the solution to this exercise?

::::::::::::::::::::::::::::::::::::::::::::: solution

This is the solution to this exercise.

::::::::::::::::::::::::::::::::::::::::::::::::::::::

:::::::::::::::::::::::::::::::::::::::

Challenge

What is the solution to this exercise?

This is the solution to this exercise.

Callouts with the tag “instructor” will render as Instructor notes, and will only show up on the Instructor view for the lesson.

::::::::::::::::::::::::::::::::::::::: instructor

This is an Instructor note.

:::::::::::::::::::::::::::::::::::::::

This is an Instructor note.

In addition to showing up in-line in the Instructor view, callouts with the “instructor” tag are gathered to a separate “Instructor Notes” page.

Scavenger Hunt (5 minutes)

Identify the file and lines of the file that control the following output for The Carpentries Instructor Training lesson. Add the file name and copy the relevant lines to the Etherpad.

  • Questions (for episode 1)
  • Timings (for episode 1)
  • Objectives (for episode 1)
  • Key points (for episode 1)
  • Instructor notes (for all episodes)
  • Setup instructions
  • Glossary

Other repository contents

Most lesson content is stored in index.md and the files within the episodes/ folder, but the lesson repository also contains source files in other folders:

  • the instructors/ and learners/ folders contain more Markdown and/or R Markdown files that will be presented as accompanying pages in the Instructor and Learner views of the lesson, respectively.
    • For example, the instructors/ folder contains the source file for the Instructor Notes page, which - in addition to collating the inline Instructor Notes inlcuded in the episodes of a lesson - can contain general guidance for Instructors.
    • The learners/ folder contains setup.md, the source file for the setup instructions that will appear on the landing page of the lesson in the Learner view.
  • the profiles/ folder contains a source file that can be used to provide learner profiles for the lesson: a way to describe its target audience.
  • the site/ folder exists to store the built version of the lesson site, and should not be modified directly.
  • the .github/ folder contains the GitHub Actions workflows that tell GitHub’s systems how to build the lesson site from the source files in the main branch of the repository. These workflows will be regularly updated by automated pull requests, and Maintainers should not modify the contents of this folder directly.

For R Markdown Lessons Only

Lesson repositories set up to build from R Markdown source files also contain the .Rbuildignore file and renv/ folder. These provide the configuration required for the interpretation and conversion of R Markdown source files in the lesson repository.

Non-source files

The other repository contents not covered elsewhere in this episode are:

  • .editorconfig and .gitignore are files that help people work with lesson repositories on their local system.
  • other files with upper-case names (AUTHORS, LICENSE.md, etc) are “repository-internal” files i.e. they are most relevant to the lesson as an open source repository, rather than as a website.

Although these repository files may be occasionally updated, Maintainers can mostly ignore them and focus on the source files for the lesson itself.

The contents of a typical lesson repository, with files and folders labeled according to whether they are relevant to the lesson content, the lesson repository, or the lesson infrastructure, and whether they are specific to R Markdown-based lessons or not.
The organisation of a typical lesson repository. Note that this figure contains some files and folders that may not be found in every lesson repository. Refer to the rest of this episode, and the full Workbench documentation, for a list of the minimum set of files and folders that are required for a lesson repository to build successfully.

Full Infrastructure Documentation

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 Introduction to The Carpentries Workbench.

Key Points

Content from The Carpentries Git Workflow

Last updated on 2024-05-16 | Edit this page

Estimated time: 60 minutes

Overview

Questions

  • How can I use git to explore and edit changes suggested by contributors to a lesson?
  • How can Maintainers make changes to their lessons?

Objectives

  • manage potential changes to a lesson using forks and branches

Maintainers and Forked Repositories

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 main.

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 default 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 main
  2. Create a new branch: git switch -c BRANCH_NAME or git checkout -b BRANCH_NAME
  3. Make changes, add, commit, and push the changes
  4. Create a PR

Working on the main 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 main
  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

Protected branches

Carpentries lesson repositories are configured with branch protection rules: safeguards to reduce the likelihood of accidentally making breaking changes to the lesson. Repositories have two protected branches:

  1. A rule preventing anyone from making changes to the legacy/gh-pages branch, which includes the last version of the lesson that existed before it was transitioned to a new infrastructure in 2023. This branch exists to enable the automated closure of pull requests made from a fork that is still using a version of the lesson with the previous infrastructure.
  2. A rule prevent anyone from changing the main branch directly. This rule exists to prevent breaking or unfinished changes from being accidentally committed to directly to the lesson.

In addition to the danger of merge conflicts, the protection on the main branch is another reason why you should follow a branching/forking workflow when making changes to a lesson.

Questions and Answers (5 minutes)

Please add questions to the Etherpad.

Key Points

  • It can be helpful to clone a pull request branch to your computer and build a local version of the lesson to see how a contributor’s changes will look in the website
  • As a Maintainer, you can choose to edit your lesson using branches on the repository or on your fork