This blog post was written specifically for my co-workers at Washington State community and technical colleges, but I suspect will be useful to anyone getting started with Github, so I am posting it here. This post is Copyright (c) 2013, Bellevue College and the State of Washington.
First, some definitions
A software tool for managing source code. Typically referred to as an SCM (Source Control/Code Management) or VCS (Version Control System).
These systems allow multiple developers to work together on the same project/product. They write code at their workstation and then check in or commit those changes to a repository. Git is a distributed VCS – which means that there is not a single, centralized server that developers must check their changes into (although it can be configured to simulate that behavior). Instead, each developer has their own (usually local) repository. Repositories can then be linked with other (usually remote) repositories. Repositories that are linked can share checked-in changes with each other – merging those changes into a common whole.
The location where committed/checked-in source code is stored, shared from, etc. A repository typically contains the source code, commit/checkin history, etc. for only one project/product.
A web-based service that provides hosting for (remote) Git repositories.
In addition to hosting Git repositories, Github also provides additional features like:
- A Wiki for each repository.
- A simple issue tracking (e.g. bug tracking) system for each repository.
- Various tools for forking/merging/etc. repositories.
So, to put it all together:
- Software developers use Git to manage repositories of source code – both locally and on Github.
- Documentation for each project/product can be maintained in that repository’s Wiki on Github (where it can be access by everybody and managed by the team).
- Bugs and other issues for each project/product can be reported, documented and managed in the issue tracking tool for that repository on Github (where it can be accessed by everybody).
Getting started with Git
If you’re not already familiar with Git – or at least some other source control tool – I’d strongly recommend spending some time learning how it works, and how to integrate it into your own workflow, before adding Github to the mix. Source control and Git itself are far too large a topic to get into here, but the following are a number of resources Bellevue College has collected:
- For more information about Git and source control in general, I highly recommend Version Control by Example by Eric Sink – which is available online, in print or a number of e-book formats – both free and for purchase.
- The Git website also has a book and some helpful videos.
- If Windows is your primary development platform, install the official Git for Windows package. I also recommend the Git Extensions collection of GUI tools, but strongly suggest you learn the command-line first.
- If you use Visual Studio for your development, vs2012’s TFS tools work with Git, but I usually recommend the Git Source Control Provider for 2010 or 2012.
- Github also has an interactive, hands-on walkthrough of using Git from the command-line at http://try.github.io
Working with Github
As previously mentioned, Github is an online service which provides public hosting of Git repositories. With your repository on Github it is easy for others to find your project, download your code and (hopefully) submit useful contributions. They can even fork your project to create a new offshoot. In addition to just hosting source code, Github provides some additional features that can be useful when collaborating with others.
Besides personal accounts Github also allows any user to create organizations. Organizations act much like accounts in that they can own repositories, but they do not have a login of their own. Instead, the person who first creates the organization becomes the first Member in a Team (similar to a role group) called “Owners”. Owners have full, administrative access to the organization. For example, they can create repositories and add new members – including adding members to the Owners Team.
While each college is free to set up their Github accounts in a manner that works best for them, I would recommend each person who is going to access Github create an account and then one of you create an organization for your college. You can see how we set up ours at https://github.com/BellevueCollege.
To create an organization:
- Go to your profile page by clicking your username at the top of the page.
- Click the Edit Your Profile button.
- Select Organizations from the tabs on the left.
- Click the Create new organization button.
Members and Teams
To add or manage members of an organization edit that organization’s profile, click the Members tab on the left and then click the team management link. Here you can
- Add accounts to/remove accounts from the Owners Team.
- Create/Remove Teams.
- Define which repositories can be accessed by which Teams.
Teams essentially provide the ability to define access groups that members can belong to. You can define the permissions (push, pull and/or administrative), members and repositories for each Team. I recommend setting at least two people from your college (3 or 4 would be ideal – so as to maintain a healthy Beer Truck Index) to be on the Owners Team for your organization and setting up another Team with Push & Pull access for granting trusted individuals the ability to make modifications directly to your code, should you so desire.
Once you are a member of an organization on Github, when creating a new repository you will have the option to create it with your account as the owner or one of the organizations you belong to. If you choose the organization as the owner the new repository will appear on the organization’s page and “belong” to that organization.
This means it will benefit from the Member and Team access that can be configured as outlined above.
Other Github tips
As you navigate your way through Github, you might find the following information useful:
- When added, members of an organization are “concealed” by default. This means:
- The member will NOT appear on the Members tab when viewed by non-Members.
- The Organization will NOT appear on the user’s profile page.
- To un-conceal a member, an Owner must click the Publicize membership button on the Members tab of the organization.
- Once your membership is publicized, the organization will appear under your picture and other information on your profile page. (See image below.)
Following, watching and starring
Github includes 3 different ways to monitor activity. To be honest, this is still an area I’m a little fuzzy on. But this is what I’ve been able fo figure out so far:
Follow other users
When viewing the profile page of another user you have the option to follow them by clicking the Follow button. I have not observed an particular notifications (e.g. via e-mail) from following another person, but they do show up in my following count and list. A lot of people have asked how to find other users and/or repositories. This is the primary way I do so – by following other people, seeing who they follow, etc.
Star repositories to “follow” them
When you Star a repository, this seems to have a similar effect as following a user. Starred repositories show up alongside the users you are following. I have no idea why Github felt the need to use different terminology.
Watch repositories to be notified of new/updated discussions
If you click the Watch button for a repository, you will be presented with 3 options:
- Not watching
There is also a short description of each, but for completeness, I will include here that selecting Watching will cause you to receive notifications for all discussions that occur in the repository.
Where do we go from here?
As we progress in our use of Git and Github, I will post additional articles on such topics as
- Ignoring files.
- Working with remote repositories.
- Merging, branching and forking.
In the meantime, I recommend the resources listed under the Getting started with Git section above.The preceding post is Copyright (c) 2013, Bellevue College and the State of Washington.