Open Leadership Training Series : Collaborative Workflow

In this module, you’ll be introduced to a good, open, welcome workflow for collaboration on GitHub. You’ll get some tips for good GitHub communications, and you’ll practice making and managing changes to repositories… You’ll play the role of both Project Lead and contributor. Get ready to make and merge your first pull requests!

60 mins Suggest changes

Format

Read, watch videos, and work with GitHub in two roles: as a contributor, and as a project lead

Prerequisites

Have completed all previous sections and modules

Materials

Your computer, GitHub account, your own project— plus someone else’s project you’ll contribute to!

Collaboration as Conversation
Writing Great Messages and Comments on GitHub
Assignment: As a Contributor, Make a Pull Request
Assignment: As Project Lead, Merge a Pull Request

Collaboration as Conversation

Good collaboration is a back and forth process, like a conversation, or a call and response. It’s not complicated, but you need to know the steps and the roles for contributor and lead. The series of videos below walks you through a workflow for collaboration on open projects, and demonstrates good communication with contributors. Watch closely, because you’ll be doing these steps (and playing both roles) yourself in the assignments at the end of this module! We’ve included screenshots in the assignment section to help you along.

If you master this workflow and practice it in your community, contribution can happen more smoothly and be more satisfying for all involved. You, the project lead, need to move this whole process forward! These handy tips should help.

Acknowledge when a new issue is posted by a contributor (remember, both contributors and project leads can post issues!)
Notify users when you start and finish work
Summarize the state of the issue
Give periodic status updates
Inform everyone if you slip
Inform everyone if you’re on track
Make responsibility handoffs clear
Notify when new functionality is added to the project, and when fixes are made
Always use friendly tone and correct grammar to increase legibility
Talk to users on their terms, follow their cues

Writing Great Messages and Comments on GitHub

Your communications on GitHub don’t need to be literary masterpieces, but it’s really helpful if they are clear and well-written. Remember the history of your document is a timeline of commits. Each “commit message” is the backstory of your changes. A good, comprehensible, useful “commit message” is one that fills in that story. It lets collaborators and the project owner/lead know what you’ve done, what changes you’ve made, what you’ve added. This includes your own commits as project lead. While you might know the ins and outs of any change you made at the moment, in 5 days or 5 weeks or 5 years, those details will probably have slipped your mind. A detailed commit will capture that information forever.

When you’re writing commit messages, you’ll want to make them short, clear, and in a fairly uniform format so they’re easy to read. Here are a few rules for writing messages like these, taken from this excellent blog post, How to Write a Git Commit Message, by Chris Beams. Read the post to learn about the rationale behind each rule.

Separate subject from body with a blank line
Limit the subject line to 50 characters
Capitalize the subject line
Do not end the subject line with a period
Use the imperative mood in the subject line
Wrap the body at 72 characters
Use the body to explain what and why vs. how

Here is an example to illustrate the above points:

Add example commit message to collab workflow lesson

An example of what a nice commit message looks like to make the points from
the lesson text more concrete.

Assignment: As a Contributor, Make a Pull Request

Find a project you’d like to contribute to and check out the README
Read the contributing.md file and code of conduct
Familiarize yourself with the project’s roadmap
Review the issues and pick one– ideally a “good first bug” that you can take on
Comment on the issue, be sure to ask if you have any questions about the task
Follow the contributor guidelines
1. Fork the repo
2. Make a branch
3. Make a commit
4. Write a great commit message
5. Make a pull request!