learning-github
Learn to use GitHub with your friendly Vanderbilt Librarians
Project maintained by Ramona2020 Hosted on GitHub Pages — Theme by mattgraham
Review
Topical reference
Commits
Branching
Cloning and Checking Out
Forking
Collaboration Models
Shared repository Model
In the shared repository model, collaborators have push (i.e. write) access to the project repository. Feature development typically happens through creation of branches, pull requests (sometimes with protracted review and discussion), and merges of forks back into the master branch. The shared repository model is well-suited for projects with a small number of collaborators and for private repositories.
Open Source (Fork and Pull) Model
In the Open Source model, project maintainers have push access to the project repository, but contributions commonly come from people outside the core team. Feature development may occur through branching and merging, but can also happen through development in forks by contributors who are not members of the core team. Those contributors suggest changes through requests to pull from their forks. Project maintainers and members of the community review and discuss the proposed changes. Approved changes are merged into the master. The fork and pull model is well-suited for projects with a large number of collaborators and for public repositories.
Fork and Pull Example
The following example involves a minor change to the master branch. The process would be the same for larger changes, although the discussion would be more extensive and the time between the initiation of the pull request and its subsequent merge (if ever) would probably be a lot longer.
Let’s imagine a scenario involving me and my alter ego, Tomy the Cat. I’ve started an open source collaborative project called the “Nashville Coding Cats” club and created a repo on my account called “code-cats-rock”. Tomy visits my site and is excited about participating. Here’s what he sees:
After he clicks on the repository name, he clicks on the Fork button at the upper left of the repository summary page.
If he has has push access to multiple accounts, he may need to choose which account to put the fork in.
The fork will now show up as a repository in his own account. To prevent confusion, the name of forked repos is commonly displayed next to a little “fork” symbol to remind the user that the repo is from somewhere else.
At this point, the forked repo will show up on the list of repos that Tomy can clone in GitHub Desktop. Now Tomy has edited the README.md page (either directly on GitHub using the online editor or on his laptop using Desktop, then pushed the changes up to GitHub).
Here’s what the forked repo page looks like now:
This is what we see after we click on the New pull request button. Notice that we have switched from the forked (head) repo to the organizational (base) repo.
Creating a pull request from a fork is a bit more complicated than a pull request from a branch because we can choose to merge from any branch in the forked repository to any branch in any other repository (including another fork) that’s based on the same original repo. In this case the situation is simple, since we are pulling from the master branch in the fork to the master branch in the original repo. The term head is used for the source branch/repo/account and base is used for the target branch/repo/account. To avoid any confusion, pay attention to the direction that the arrow is pointing in the dropdowns used to select branches and repos. Click the Create pull request button to begin the pull request.
The email generated by the @mention has links to the pull request so the project manager can go straight to it on GitHub.
Clicking on the link in the email takes the project manager to the pull request. The manager can do the merge or make further comments with requests for changes.
After doing the merge, the changes have been added to the original project.
Back in Tomy’s account, he can now decide whether he wants to keep the fork or not. If there isn’t really anything useful for him to do with it (since his changes were pulled into the main project), he can go to the settings for the repo and delete it.
Note that deleting the fork will have no effect on the original repository. Caution: do not delete the fork before the changes have been pulled into the organizational (base) repository! If you do, it will be impossible to complete the merge.
In summary, the process of making pull requests to move changes into the organizational repository from a forked repository is very similar to pulling in changes from a fork within the same repository. The main difference is that there are more options for selecting the repository and forks to be used both at the head and base of the merge. For example, a branch created only in the forked repo could be merged directly into the master of the original repo, or merged into the master of the fork, THEN from the fork master to the original master.
Managing Projects with GitHub
In addition to the tools that allow GitHub to carry out its core functions (commits, forking, branching, pull requests), GitHub has a number of other tools that make it possible for organizations to plan and track the work that they are doing on document-based projects. On this page we’ll introduce several important ones.
Collaboration infrastructure: 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. However, at this point in time, the organization can only have public repositories. So for operations like labs that might want to have private repos, you’d need to use the P.I.’s account to create a private repo.
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.
In a personal account, other users can be granted push access as collaborators, but personal accounts can’t have teams. An advantage of teams is that they can be @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 if they are open, or part of a paid account.
Tools for tracking progress
There are three tools that allow you to track your progress on a project at three levels of granularity. The finest-scale tool is the integrated issues tracker that we can use for keeping track of work on tasks and general communication. At the medium-scale there are milestones, and for the large scale there is the projects tool.
Using the issues tracker
The issues tracker is a way to keep up with very particular problems associated with a project. They may be associated with a particular document or may be a general, overarching problem.
To create a new issue within a particular repo, click the issues tab. You’ll see the list of existing open issues (if any). To create a new issue, click on the New issue button.
Enter a title for the issue and write text explaining the issue in the box. You can use the @mention system to make sure that relevant people are informed about the issue. If you want to assign the issue to some particular team member, clicking on the Assignees item will give a dropdown list of collaborators.
It’s also a good thing to assign a label to the project. Labels are like tags in other systems. Assigning a label categorizes the issues so they can be searched. It’s also a very visual way to know the status and category of an issue and shows up in the issues list.
When you click on the Label item and a dropdown of possible labels appears. You can select one of the labels or click on the Edit icon to create a new label.
We don’t see the label we need, so click on the New label button. You can select the name, description, and color you want, then click on the Create label button.
Once the label is created, you can select it and any other labels you want to apply. Back at the issue editing screen, you can click the button to submit the new issue.
Anyone on the team can reply to the issue and GitHub tracks all of the actions taken related to the issue. You can also cross-reference other issues by typing the issue number after a hash (#) character.
In the rendered comment, you can mouse over the linked issue to see the details. When the issue is resolved, you can close it with a comment.
The reference to the issue also shows up in the record of the referenced issue.
In writing comments, you can use any of the normal Markdown formatting features as well as to add hyperlinks to anywhere within or outside of Github.
You can use the preview tab to see how it will look. Here’s how the final rendered version looks.
Using the issues tracker as a mailing list
You can “watch” a repo by clicking on the Watch button at the upper right of the screen. Watching a repo notifies you of all conversations related to the repo, so depending on your settings, you can get an email whenever someone creates an issue or comments.
This provides a convenient way to manage an organizational email “listserv”. An “issue” can actually be something like a meeting announcement, with links to agendas, Google Hangout links, etc.
Because responses to the issue are tracked on the same page, this effectively keeps the “thread” organized sequentially. If any collaborator loses the email, they can always find the message by looking at the issue.
Here’s what the email looks like that was generated by a response to the original meeting announcement issue. The response is in the body of the email text. There is also a link that will take the reader directly to the issue page on GitHub for additional responses. Responding to the email automatically adds the response as a comment to the issue thread.
When the issue is closed (in this case after the meeting has occurred), the issue disappears from the open issues list, although it remains in the closed issues list as a permanent record of the conversation.
Using the issue tracker in this way makes it possible for project participants who are less involved in the activities to see at a glance what’s currently going on with the project, simply by looking at the open issues on the tracker.
It is also extremely easy for anyone who is annoyed with the amount of message traffic to simply unfollow the repository temporarily or permanently.
Milestones
Milestones are a way to track the progress towards a goal. They are composed of issues or pull requests that must be completed before a goal is complete. To see milestones or create a new one, click the Milestones tab on either the issues or pull requests page. If you have any existing milestones, you’ll see them listed with an indication of the progress towards completing them. Progress is measured by the fraction of issues or pull requests that have been closed.
If you have created a new milestone, or want to add to an existing one, open the issue or pull request that you want to add (or add the issue to a milestone as you create it). Click on the milestone item. That will open a dropdown with lists of possible milestones. Select the one to which you want to add the issue.
On the milestone summary page (reached from the Milestone tab on the issues or pull request page), there is all kinds of information about the issues in the milestone. If you click and drag the left side of a selected issue, you can order the issues. As issues are resolved, they disappear from the open list and the progress goes towards 100%. Closed issues can still be viewed from the Closed tab. Clicking on an issue or pull request in the list will take you to its page. If a new issue is created from the milestone page, it will automatically be associated with that milestone.
When all issues in a milestone have been completed, the milestone itself can be closed. It does not disappear, it simply moves to the list of closed milestones.
Projects
An even more powerful tool is available for managing entire projects. It can be used in place of milestones, or together with milestones to manage individual parts of the project. 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.
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).
When a pull request is merged or an issue is closed, their card automatically moves to the “done” column.
Cards can also be manually moved from one column to another and additional columns can be added.
An additional feature that we won’t discuss today is reviews. One can request a review of a pull request. A reviewer can make comments, approve a merge, and request changes. A repository can also be set up with rules about the conditions under which a branch can be merged, including a requirement for approval of a reviewer before the pull request can be merged. This can provide extra protection for master branches that serve a critical purposes, such as providing the code for a website.
More !!!
An additional powerful feature of GitHub is free hosting and management of websites using GitHub Pages. Pages can be written in Markdown, then rendered as HTML by the Jekyll system according to pre-configured or customized templates. Unfortunately, we don’t have time to talk about Pages today.
For more information and a topical breakdown of what we’ve studied in this workshop, visit the libraries’ Digital Scholarship website at https://heardlibrary.github.io/digital-scholarship/manage/control/github/.