Content from Welcome to the Maintainer Community
Last updated on 2024-03-11 | 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.
Before The Course Begins
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.
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-05-16 | Edit this page
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!
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:
- Adding the “invalid” label to the issue/pull request
- 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.
Top Ten Tips for Managing Issues and PRs
- 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!
- 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.
- 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.
-
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. - 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.
- 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.
- 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.
- 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.
- Do close issues that have gone stale, are outdated, or out of scope (after explaining why).
- 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 2024-02-22 | Edit this page
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:
- Library Carpentry Maintainer teams
- Software Carpentry Maintainer teams
- Data Carpentry lessons have an additional level of structure, as each lesson belongs to a curriculum within this Lesson Program. You can tag the full set of Maintainers for an entire curriculum (e.g. Ecology) using the team names listed here or click on your curriculum and then “Teams” on the top menu to find the name of your lesson team.
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:
- The Carpentries Clippings - our twice monthly newsletter
- @thecarpentries@hachyderm.io on Mastodon
- The Carpentries blog
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
- Maintainers TopicBox list (public)
- Maintainers Slack channel (private)
- Your lesson’s GitHub repository
Highly Recommended
- Maintainers RFC GitHub repository
- Any TopicBox lists or Slack channels related to your lesson
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
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.
- Needs elevation to CAC
- Simple fix by a single Maintainer without review
- Put in a PR and wait for another Maintainer to review
- 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 2023-07-26 | Edit this page
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 is an exciting time for The Carpentries Lesson Infrastructure! We are in the midst of the official transition to a new infrastructure - The Carpentries Workbench, which is designed to be more user friendly for both contributors and Maintainers. All lessons will transition to using the Workbench in May 2023. This episode will teach you some of the most important elements of the Workbench that you will need to interact with as a Maintainer. Full documentation can be found on Introduction to The Carpentries Workbench.
Important: Resolve All Open Pull Requests
In order to prepare lessons for The Workbench transtion, all open pull requests must be merged or closed by 1 May. The Carpentries Curriculum Team will be assisting Maintainers across all of our lessons to ensure pull requests are resolved before the deadline.
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.
:::::::::::::::::::::::::::::::::::::::
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/
andlearners/
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 containssetup.md
, the source file for the setup instructions that will appear on the landing page of the lesson in the Learner view.
- For example, the
- 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 themain
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.
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
- The Carpentries lessons share a consistent style, which is controlled by The Carpentries Workbench and documented in the Introduction to The Carpentries Workbench.
Content from The Carpentries Git Workflow
Last updated on 2024-05-16 | Edit this page
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
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 clone
ing 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:
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.”
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 clone
d 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.
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.
Practice using the recommended workflow
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)
- M: Create a repository:
<date>-collab-example
and initialise it with aREADME.md
file so the repository is not completely empty. - M: Add C as a collaborator under the repository settings.
- C: Accept the collaboration invitation (check your e-mail)
- M + C:
clone
the repository to your local machine - M + C: Both add your name to the
README.md
file - M + C:
add
andcommit
your changes - M + C:
push
your changes to the remote - M + C: someone will have a merge conflict
Working on a new branch (15 minutes)
- Make sure that your local version is up-to-date:
git pull origin main
- Create a new branch:
git switch -c BRANCH_NAME
orgit checkout -b BRANCH_NAME
- Make changes,
add
,commit
, andpush
the changes - Create a PR
Working on the main
branch
- C: fork the repository from M
- C:
clone
from your respitory (c/<date>-collab-example
) - M + C: Both add your name to the
README.md
file - M + C:
add
andcommit
your changes - M + C:
push
your changes to the remote (C: it will be yourorigin
) - C: Issue the PR
- M: Review and merge the PR
- C: Setup the upstream remote
- C: Sync the upstream changes to your local machine and your fork
Repeat but using a branch
- Make sure that your local version is up-to-date:
git pull origin main
- Create a new branch:
git checkout -b BRANCH_NAME
orgit switch -c BRANCH_NAME
- Make changes,
add
,commit
, andpush
the changes - Create a PR
- M: Review and merge the PR
- C: Setup the upstream remote
- 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:
- 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. - 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