Collaborating with your Team

Last updated on 2025-07-31 | Edit this page

Overview

Questions

  • How will I know when something happens or needs my attention on the lesson project?
  • What communication channels should we set up to aid collaboration?
  • What can we do to encourage regular progress on the project?

Objectives

After following this section, participants will be able to:

  • Manage GitHub notifications to receive relevant updates about activity on their repository.
  • Choose a routine and channels for working with collaborators on the project.

Staying in the Loop

GitHub provides a useful notification feature for collaborative work - mentions. The mention system notifies team members when somebody else references them in an issue, comment or pull request. You can use mentions to notify people when you want to check a detail with them, or let them know something has been fixed or changed (this is much easier than writing out all the same information again in an email!). In repositories belonging to an organisation rather than an individual user, Teams of users can be created and mentioned collectively, sending a notification to all its individual members.

Typing @ in GitHub will bring up a list of all accounts and teams linked to the repository that can be mentioned. You can also mention people who aren’t linked with the repository, but they won’t be listed in the @ drop-down list so you will need to know their GitHub username in order to mention them.

When Will I Be Notifed?

By default, a user will be notified when they are mentioned, assigned an issue, asked to review something, and when some activity occurs on an issue or pull request that they opened or commented on previously. These settings can be adjusted for individual projects via a dropdown on the landing page of the repository.

GitHub's different notification settings menu when watching repository events with 'All Activity' highlighted
GitHub’s different notification settings menu when watching repository events with ‘All Activity’ highlighted

You can choose to ignore a project, meaning that GitHub will never notify you about activity on that repository even if you are mentioned directly. Or you might prefer to “watch” the project, receiving updates on any activity on the repository e.g. whenever somebody opens a new issue or pull request, or comments on an existing one. There is also the option to further customise notifications.

How Will I Be Notified?

In the settings for your GitHub account, you can also choose where these notifications will appear. GitHub can send you emails to multiple addresses or add notifications to an “inbox” page in the GitHub web interface. You can configure where you want different kinds of notifications to be sent, and even customise these settings from project to project.

If you work on multiple projects, or the projects you follow on GitHub are particularly active, the volume of notifications you receive can quickly become overwhelming. Here are some approaches you can take to help you stay on top of things, and distinguish the high-priority tasks and important updates from the regular traffic.

Email Notifications

If you want to filter, organise, and redirect email notifications from GitHub, here are some characteristics of the messages that you make use of:

  • All GitHub notifications are sent from the address notifications@github.com.
  • Notification emails are sent to the address repo-name@noreply.github.com, where repo-name is the name of the repository where the notification was triggered.
  • The email subject begins with [org-or-user/repo-name], where org-or-user is the name of the organisation or the username of the user who owns the repository and repo-name is the name of the repository where the notification was triggered.
  • In addition to your email address, the cc field of the message contains an address that describes the type of event that triggered the notification.
    • author@noreply.github.com for activity on an issue or pull request that you opened.
    • mention@noreply.github.com for a mention of your username.
    • team-mention@noreply.github.com for a mention of a team you are a member of.
  • The email header (metadata) includes a mailing-list field with an identifier in the form repo-name.org-or-user.github.com, which can be used to filter by the project and/or its owner.

GitHub provides detailed documentation about all of the properties you can use to filter their notification emails.

Most email clients provide configuration for rules that can be set to redirect messages to particular folders, and/or to annotate them with a mark or flag, based on this kind of information. Here is the documentation for setting such rules in Gmail.

Notifications on GitHub.com

The GitHub notifications inbox page includes several preconfigured filters:

  • Group notifications by repository.
  • Review notifications for a particular repository.
  • Review particular types of notification e.g. mentions, issue assignments, etc.

You can also create your own, more sophisticated filters, using the search bar, e.g. all mentions for all repositories in a particular organisation.

Whatever strategy you choose, one of the most important habits that will help you stay on top of your projects and tasks is to remember to check these notifications frequently.

Working Together

Talking to Each Other

In addition to tracking and responding to activity on your repository, effective teams typically maintain other channels of communication. These channels can be useful for more informal communication and back-and-forth discussion that is less suitable for a public discussion thread on GitHub.

Slack is commonly used in the Carpentries community for quick, day-to-day message exchange. You should join the Carpentries Slack workspace to connect with other lesson developers. Once you join, you can join the lesson-dev channel, which is dedicated to discussion of lesson development, and create a channel for your own project under the Carpentries public Slack workspace. If you need more complex team communications (e.g. multiple channels) you can create your own Slack workspace. Workspaces can be created for free but carry some restrictions e.g. on message volume and history, and file storage. The Carpentries Slack is an enterprise workspace and is not subject to these limits.

Collaborators may also choose other platforms to discuss lesson development or receive contributions from newcomers who are not yet fluent in using GitHub’s systems of communication. The Carpentries can assist with creating a mailing list specific to the development of your lesson on our TopicBox platform for managing threaded email discussions. Also make sure to join the Incubator lesson developers mailing list on TopicBox to keep an eye on announcements and discussions relating to lesson development within the Carpentries community.

The exact channels and cadance of your communication will largely depend on the personal preferences of your team members. The best thing you can do is devote time in an upcoming meeting/coworking session to discuss and agree on where and how you will communicate about the project.

Making Progress

The following practices have been shown to help maintain steady progress with lesson development:

  • Being responsive to notifications about activities and mentions.
  • Scheduling regular co-working/sprinting sessions with team members (e.g attaching your sprint sessions to other open source community activities, which may offer goodies, rewards and prizes for participants, can provide motivation and activity spikes).
  • Working alongside other members of The Carpentries community at Maintainer or lesson development co-working sessions.
  • Blocking time in your calendar for issue triage/solo material writing.
  • Planning lesson pilots in advance to help set targets.
Key Points
  • GitHub’s notification settings can be customised to provide the updates you need in the places where you want them.
  • Effective communication is essential to good collaboration.
  • Regular progress can be achieved by ensuring your team members have frequent opportunities to discuss the project.