Digital Education Resources - Vanderbilt Libraries Digital Lab

Previous lesson: issues tracker

GitHub for beginners: Collaborative project management

In this lesson, we delve into the complexities of working with collaborators to manage text-based files. We look at the Kanban-style GitHub Projects board to see how it is integrated with issues and pull requests. We then examine in detail the use of branches and pull requests to allow feature development to happen independently from the main production branch of a repository.

Learning objectives At the end of this lesson, the learner will be able to:

Total video time: 16 m 2 s

Links

Lesson slides

Project boards (1m32s)

GitHub includes the capability to create project Kanban boards associated with a repository. These boards use “cards” sorted into columns and are similar to other project management tools like Trello. However, the cards on the board can also be issues or pull requests, so they are integrated with other code management tools that are specific to GitHub.

.

As of 2022-02-29, GitHub has a beta version of projects with several new features. The cards of the project to be viewed and sorted in a tabular form (rather than as a board). The project can also be managed on an organization-wide level, rather than being associated with a particular repository. That allows the board to include issues from the trackers of several repositories.

Setting up a project (1m47s)

.

When creating a new project, you can select a template for the project. I recommend “Automated kanban”. It is pre-configured with “to do”, “in progress”, and “done” columns and uses triggers to automatically move issues and pull requests through the system.

Creating cards (2m13s)

.

The main component of a GitHub project is a “card”. Cards can be added manually using “Add cards” on the board. However, they are more often generated automatically by assigning an issue or pull request to the project.

When the pull request or issue is created, it automatically gets added to the correct column in the project board (To do for issues and In progress for pull requests).

Managing the project (2m08s)

.

When a pull request is merged or an issue is closed, its card automatically moves to the “done” column.

Cards can also be manually moved from one column to another and additional columns can be added.

Working with collaborators and organizations

Inviting collaborators and creating organizations makes it possible for more than one person to contribute to and manage a repository.

Inviting a collaborator

Find out the username of the person you want to invite to collaborate with you. Either collaborator can set the repo up, but it can only be on one person’s GitHub account.

alter ego image

In this example, I’m going to invite Tomy, my alter ego who uses my test baskauf account, to share a repository on my real GitHub account baskaufs (with an “s”). Go to a repository you want to share and click on the Settings tab.

menu location

Click on the Manage access link.

access link

You may be asked to provide a password to confirm access. Click on the Invite a collaborator button.

invite collaborator button

In the popup, start typing the name of the collaborator you want to invite and select it from the list when it appears.

select collaborator dialog

Click the Add ... button.

add to repo button

You should see them as a pending invitation in the list of collaborators.

pending on list

When Tomy checks his email, he should see an invitation to collaborate and a link.

invitation email

Sometimes the email takes too long to arrive, or gets sent to spam. If so, the invited collaborator can speed up the process by attaching /invitations to the end of the repository URL. If they are logged into GitHub, they should see their invitation at that link.

Here is what Tomy sees when he goes to that link.

invitation page

When he clicks on the Accept invitation button, he will be taken to your repository, where he’ll see a notification at the top of the screen saying he now has push access to the shared repo.

push access notification

Accessing the shared repository

Once the collaborator has push access, they can clone it using GitHub Desktop and start using it just as they would one of their own repos.

To clone the newly shared repository using Desktop, Tomy should drop down the arrow to the right of the current repository name, then drop down Add, followed by Clone Repository....

list of shared repositories to clone

On the GitHub.com tab, he will scroll down past his own repositories until he sees his collaborator’s account name. Under that account, he should see the newly shared repository. After he selects it and chooses the location in the directory where he wants it to go, he clicks the Clone button and starts using it.

Organizations and teams

Once you embark on collaborative work, you will probably need to set up infrastructure that is not dependent on your personal GitHub account. One key is to set up an organization. Creating an organization allows repositories to be jointly owned by several people, so if an organizer leaves the organization, that person can be disentangled from the repositories without having to remove material from their personal repository.

Anyone can create an organization for free. As of February 2021, free accounts can have unlimited public and private repositories, and unlimited colaborators. There doesn’t seem to be a hard limit of size, but less than 5 GB per repository is recommended.

Once you’ve set up the organization, you can add members, change their status (owner, member, outside collaborator), grant administrative privileges to repos, and establish teams. The ownership of the repository can be granted to other members in the event that the person who created the organization leaves it.

An advantage of teams is that they can be notified (@mention’ed) as a team rather than individuals, and team members can have conversations that aren’t limited to an issue, pull request, project, or repository. Teams also are a way to control levels of access to particular repositories. Members of the organization can request to join teams, and their requests can be approved by a team owner or maintainer. So teams may be a good option for large projects.

Branches and pull requests (1m58s)

Branches

branches and commits

In an earlier lesson, we defined a branch as a set of files that changes over time. A repository can have several branches at the same time and each one is maintained with its own record of commits over time.

The primary branch of a repository is called the main branch. In a very simple repository, the main branch may be the only one. But more commonly, there are several branches that have been created by branching them off of main. (“Branch” is both a noun and a verb in Git.) When you create a branch from the main branch (or some other branch), it begins with exactly the same files as its source. It also carries the commit record of its “parent” branch as well.

The purpose of a branch is to allow for the development of documents independently of main. You might choose to create a branch if you want to develop a new feature of software you are developing, or you may create a branch if you are creating a significant revision of a document. Working in a branch allows you to “take risks” without the danger of possibly messing up the main branch. This kind of branch is called a working branch or a feature branch.

There are several possible fates of a branch. A common fate for a working branch is for it to be merged back into the main branch. This can happen when the revision is complete, or if the new feature has been debugged and is ready to be deployed. You might also decide that development of the branch is hopeless, and just delete it and return to main. In some cases, a branch may remain as a separate entity from the main branch` with no intention of ever merging it. This is a common practice when using GitHub Pages to manage a website.

Historical note: In the past, the primary branch of a repository was called master. In order to foster more inclusive terminology, as of October 2020 GitHub has changed the default name for the primary version of repositories from master to main. However, you will still see some old repositories using master for the primary branch as it may be disruptive to change the name of a production branch.

The Shared Repository model

The Shared Repository model is one of the two major ways that development is coordinated in large projects that involve more than a few collaborators.

shared repository model diagram

In the shared repository model, all collaborators have write access to the repo. They push changes to the branches they are working on directly to the shared repository.

This model is common when teams are relatively small, and especially when development is not open to the public. The other model, Fork and Pull (also known as the *Open Source model), is common in large, open source projects where features may be created by contributors who aren’t on the core team, and therefore don’t have write access to the repository.

merging a pull request

Individuals can simply merge a feature branch back into the main production branch, but if they are working as part of a team, there are usually social conventions governing the circumstances under which a feature branch is merged into main.

Before carrying out a merge, one of the collaborators creates a pull request. A pull request is NOT a request to immediately merge, but rather indicates the beginning of a review and dialog about the proposed changes. A significant amount of time can elapse between a pull request and a merge, and additional changes may be required on the working branch before its changes are actually ready to be incorporated into the master. (Note: “pull” in the context of pull requests means to pull changes from a branch into the master. That’s a different process from “pulling” changes from GitHub to a cloned local repository.)

This workflow of branching, pull request, reviewing, and merging is sometimes called GitHub Flow. Some version of it is used by many organizations that utilize GitHub.

Creating a branch (1m33s)

.

Note: these screenshots show the old default production branch, master. The current default is main.

In this example, my coworker has created a repository called feline-cuisine and has invited me to be a collaborator. I have accepted and have cloned the repository to my local computer.

When I click on the Current Branch tab of the desktop client, here’s what I see:

Currently, there is only one branch, main, in the repo.

I want to work on the project, but would prefer to develop my changes on a separate branch. So I click on the New Branch button. In the resulting popup, I give the branch a descriptive name.

Then I click on the Create Branch button. The GitHub Desktop automatically checks out the new branch and lists it as the current branch.

Note that at this point the branch only exists on my local copy of the repository. If I want, I can click Publish branch and the new branch will be created in GitHub. Alternatively, I can edit and make commits before pushing the branch.

Changing to a preexisting branch

The process of creating a representation of a branch in your local file system from data that git has documented in a repository is called checking out that branch.

By default, the desktop client checks out the main branch of a newly cloned repo. However, if that repo has more than one branch, you can change from the master branch to another branch by dropping down the middle “Current Branch” menu at the top of the window.

When you select a different branch in this dialog, the desktop client will check out that branch.

Checking out a branch literally changes the files that are present on your local computer. For example, when I selected the master branch as my current branch, here’s what several directories looked like:

You can see that the pylesson directory has a lot of files in it and the lod directory doesn’t. If I change to the “gh-pages” branch:

then I’m checking out a different set of files. Here’s what the directories look like now:

Some files have disappeared, like the ones in the pylesson directory, and other files have appeared in the lod directory. The content of the files themselves may also change if the state of the files is different in the two branches. Note: Git only manages files, not directories. When Git checks out a different branch, it doesn’t delete directories, even if they don’t contain any files in that branch.

GitHub work cycle

It’s important before you start working on files that you are clear what branch you currently have checked out. Recall that the first step in the GitHub work cycle is not only to select the repository you want to work on, but also to make sure that you have checked out the proper branch.

It is also important to make sure that you’ve saved the files that you were working on before you check out a different branch in the same repository. It is possible to lose unsaved changes if you don’t, although usually the desktop client is smart enough to give you some kind of warning first.

If you switch the GitHub Desktop to another repo, it will remember what branch you were working on the next time you switch back to that repository.

Creating and reviewing a pull request (4m51s)

.

Once I’ve solved all of the problems I noticed, my changes need to be merged into the main branch. To start that process, I need to create a pull request to initiate discussion about my changes.

If I click on the Code tab in the online repo. I see a notification of my recently pushed branch, with an option to open a pull request.

The resulting page has a lot of useful information. Importantly, there is a list of commits with their corresponding messages. You can see why it’s important to create commit messages that succinctly state what was accomplised with each commit. Since I’ve edited Tomy’s document, it would be appropriate for me to request that he review the pull request (see the Reviewers option in the upper right). The full set of changes to the file are shown at the bottom of the page – if I want to see what was done in each commit, I can click on the commit message in the list. Notice that in the text of my comment, I can refer to an issue by putting its number after a hash mark. After I click on the Create pull request button, Tomy will receive a notification about the review (by email, if his settings allow).

I could merge the pull request myself, but our team has established a policy that merges should always be done by someone other than the creator of the pull request.

Review and merge

Since my collaborator has his notifications settings set to receive notification emails, he receives two emails. One notifies him that he has been requested to review and the other is a general summary notification of the pull request:

When he clicks on the link in his email to go to the pull request, he sees the review request:

After he clicks the Add your review button, he’s taken to the review screen where he writes his review and indicates his approval.

Clicking on the Submit review button generates a notification to me that he’s reviewed the request and agrees. After submitting his review, he’s taken back to the pull request screen where his review has been added to the history of the request.

If he’d disallowed the merge, he could have closed the pull request without merging. But instead he clicks the Merge pull request button. Confirmation is requested, and after confirming, the steve-suggestion branch is merged into the master branch.

The commits that were made in the steve-suggestion branch are now part of the master branch and will appear in its history. The working branch is no longer needed and can be deleted from the online GitHub repo by clicking the Delete branch button. However, that does NOT delete the branch from any local repositories on the desktop computer. To delete the unneeded repo from it, go to the Branch menu on the desktop client and select Delete....

If you hadn’t already deleted the branch on GitHub, you could check the box to delete it at the same time. After deleting, the desktop client will automatically switch back to the master branch. Checking the history tab, we see the commits from the working branch now incorporated into the history of the master.

Creating a patch branch

Usually, one would develop a document using a working branch on a local computer and manage commits using the desktop client. However, it’s possible to make minor edits using the online editor through a patch branch. The process is similar to what was described above - to see details, go to this page. That page also shows how to resolve a merge conflict using the online editor.

Protected branches

The instructions above assume that all collaborators have unrestricted push access to the repository. In order to add a degree of protection to the main branch (or any other branch), it can be protected by adding additional requirements that make it more difficult to change. For more details, go to this page.

Practice assignment

Note: some of these activities require another GitHub user to collaborate with you. You should do each of the activities reciprocally so that you can practice both requesting and responding.

  1. Create an automated kanban style GitHub project (classic, not the new beta style).
  2. Add several issues to the project and see where they ends up in the board. Add one by selecting the project from the issue page and add another using the Add cards feature on the project board page.
  3. Move an issue to In progress by manually dragging it into that column.
  4. Go to an issue from the board by clicking on the card and selecting Go to issue for full details.
  5. Close an issue to move it to the Done column.
  6. Invite another GitHub user to collaborate with you in a repository.
  7. Accept an invitation to collaborate in another user’s repository and clone that repository to your local computer using Desktop.
  8. Create an issue in your collaborator’s issues tracker, assign it to your collaborator, and add it to their project.
  9. Create a working branch in the shared repository using desktop and publish it to GitHub.
  10. Make a commit on the working branch and push it to GitHub.
  11. Create a pull request for the working branch and request a review from your collaborator.
  12. Respond to a review request of a pull request.
  13. Create an additional commit to your working branch and see how it appears on the pull request page.
  14. Merge a pull request.
  15. Delete a merged branch both on your local computer and on GitHub.

Next lesson: GitHub Pages websites

Revised 2022-02-21

Questions? Contact us

License: CC BY 4.0.
Credit: "Vanderbilt Libraries Digital Lab - www.library.vanderbilt.edu"