Github

From W3C Tools Support Wiki
Jump to: navigation, search

W3C uses Git and Github to manage work on specifications and other documents. Git is a collaboration and version control tool. Projects are managed in Git repositories (known as "repos"), and Github is a web-based collection of Git repos.

Get an account

You will need a Github account to work on W3C projects. There are free and paid Github accounts, but for collaborating on W3C projects the free account is fine.

Get a client

You can do most things on the Github website, but there are times when you'll need to use a client on your local machine. You can use the Github desktop client, or you can use Git (and consequently Github) from the command line.

Get setup

You will need to setup your client to associate it with your Github account. When this is done you will be able to start collaborating on W3C projects.

Using clones

You can download a copy of a repo to your local machine. The copy is known as a clone. If you have sufficient privileges; you may synchronise your clone with the original repo (known as the master). When changes are made to the master, you can update your clone to reflect those changes.

Using forks

A clone is a good way to look at the contents of a repo, but it is generally a passive activity. If you want to make changes to the repo, you can create a fork instead.

A fork is a copy of a repo. When you create a fork, a copy of the master repo is placed in your Github account and you can clone it to your local machine from there.

You can make changes to your fork, without affecting the contents of the master repo. If you want to propose that your changes are added to the master, you can issue a Pull Request (PR). The owner of the master repo can then choose to pull your changes into the master repo, or reject them.

Using issues

You can file and discuss bugs, and set and assign tasks for a repo using Github Issues.

When you create a bug or task you can use markdown to format your comments.

Watching repos

If there is a repo that you are interested in, you can watch it. This means you will receive a notification whenever some activity takes place on the repo.

You will automatically receive notifications whenever someone mentions you in a PR, comment or commit message. Github mentions use @username syntax.

Using notifications

You can choose to receive notifications via the Github website, by email, or both. You can respond directly to issue threads by replying to the email notification.

Tip: When replying to issue threads by email, do not blanket include the content of the original email. Include relevant quotes only.

Getting help

Use Github help to find out more about using Git and Github. There are also many guides to using Git and Github to help you get started.

There is also useful information elsewhere to help you use Git and Github for W3C projects.