This is an early draft, primarily authored by npdoty with notes from some W3C team members. Advice should be taken with grains of salt, to taste. Interpretation of W3C Process is best left to W3C legal counsel; interpretation of your Working Group's preferred workflow is best left to your group and its chairs, editors and team contact.
Git is a popular, open-source distributed version control system, commonly used with GitHub as a convenient central host of repositories, along with wiki documentation, pull request management and issue tracking. Several W3C groups are using GitHub infrastructure for specification and test authoring workflows. Below we include some suggested steps for getting started and answers to some frequently asked questions about using GitHub for W3C spec work.
- 1 Questions
- 2 Getting started
- 3 Tools
How do we ensure archiving of work done on GitHub?
As usual, publication of Working Drafts and Recommendations into w3.org/TR/ will be done by your Team Contact by copying snapshots which satisfy pubrules into the appropriate space, with W3C-guaranteed archiving.
A common use case would be for editors' drafts to be pointers to the head revision of a git repository's master branch as it appears on GitHub. Because Git itself decentralizes archiving of every change (every user clones all history), backups of version history of Git repositories should be straightforward. W3C systeam is considering automated W3C backups of repositories within the GitHub W3C organization.
Issues, wikis, pull requests and other GitHub-hosted workflows may not be as straightforward to archive, and your group members may need their own GitHub accounts to make effective use of those features. GitHub repository wikis are themselves Git repositories, so backup should be relatively simple.
When should we use Git/GitHub as opposed to w3.org-hosted CVS or Mercurial?
tl;dr -- your version control system is up to you and your group, but GitHub is growing increasingly popular among our Working Groups.
W3C has no official recommendations of what version control system your Group should use. Your Group's editors will be the ones most often using the chosen version control system, and your Group's participants may have their own preferences regarding viewing version history or proposing changes. GitHub has some real advantages for specification and test authoring: histories of changes are all public; Git and GitHub are commonly used tools among developers; easy branching can facilitate sharing in-progress proposals, etc. With CVS editors and chairs can make direct changes to w3.org-hosted specifications, but setup also requires an SSH key setup process with w3.org systeam.
Should we use GitHub for issue management too?
Different groups have had different preferences on the best way to manage spec issues and code issues. Repositories that manage test code often use GitHub issues extensively or exclusively, and they may also work well for issue workflows where an editor's single commit will often be the resolution of an issue or pull requests are commonly used.
Bugzilla is often used by groups (like HTML WG) that have a relatively complex issue resolution process.
Tracker is particularly useful for integration with IRC trackbot and connecting mailing list discussion of an issue. (Tracker also separately tracks "actions" which are not present in GitHub's workflow.)
As with any specification, text contributions with IPR implications should be included only from formal participants in a Working Group who have made the necessary IPR commitments. Likely only the Working Group's editors and chairs should have commit privileges to your group's specification repositories. Editors should take special care when accepting Pull Requests that the appropriate IPR commitments have been made (as you do with text suggestions made to the group mailing list); chairs and staff should make sure editors understand this.
Informal drafts in your personal account
Getting started individually doesn't require any approval process. Create an informal draft (using ReSpec makes it easy) by starting a new repository with your personal GitHub account. We recommend one repository per deliverable, in general.
You can link to ReSpec directly from your source. Use a gh-pages branch to let others easily see the rendered version of your draft hosted on the Web (more details below).
Hosting a repository within the W3C organization
1. Your Team Contact should become (if they're not already) a part of the Owners Team of the W3C organization. (Ask any of the current owners directly, or ask on &sysreq. This is only for W3C Staff.)
2. Team Contact should create a new Team for the editors (and optionally, the chairs) who will be contributing to the Group's deliverables. Give each editor push and pull access.
3. Create a new repository for each deliverable (like a Recommendation-track spec), or fork an existing informal draft into the W3C organization. Add each such repository to the "Team" so that the editors/chairs all have commit access. Other participants in the Working Group can suggest changes by submitting pull requests (in fact, editors can do that too to make the process more clear, if desired), but not every contributor will be given direct commit access.
Detailed steps for staff contacts to create a repo
- Let's say you're working on the unicorn spec. You head to https://github.com/new (which is linked as "New repository" from the home page). Under Owner you pick "w3c" (which you should have access to, if not ask someone on IRC) and under repo name you pick "unicorn". Enter a description, keep it public, initialise with a readme, don't pick a .gitignore or a license.
- Now go to https://github.com/organizations/w3c/teams/new. Give the team a name ("Unicorn Editors") and grant them Push & Pull (no need for admin). Save the team. Under "Members", just start typing the user names for the editors, you'll get a drop down suggesting people. Once you've added them all, under repository start typing "unicorn" and you should see w3c/unicorn listed. Pick that.
- That will give you a https://github.com/w3c/unicorn with fully configured access. From there you can follow the instructions in Tobie's document.
In specification development, the reader will most often want to read the spec itself, rather than the raw HTML source code. GitHub provides easy functionality for this via the gh-pages branch and GitHub Pages.
You have a couple of alternatives. Get rid of the default master branch:
- create a gh-pages branch: in your local clone do git checkout -b gh-pages (that will create a separate "gh-pages") branch, followed by git push origin gh-pages (to push this branch back to the repository).
- go to the repository, choose "settings", and select "gh-pages" as the default branch.
- delete the master branch, ie, git branch -D master
- commit to the gh-pages branch, or merge feature branches into gh-pages (e.g., git push origin --delete master)
You should also create an index.html file on the top level of the repo. That may be the document itself or, if the repo has a more complicated structure, it can be a separate index file of your choice.
Once you have made these changes, the content of your documents will be available through http://w3c.github.io/$reponame/. (It takes a while for the system to make this URI available, be patient…)
The Using GitHub for Spec Work guide describes how to get started using this method and starting with a template and ReSpec; that can be renamed index.html to simplify your URLs.
Alternatively, you can continue to use the master branch for development and writing but use a post-commit hook to simultaneously push those changes to gh-pages.
It is worth downloading the 'official' GitHub for Mac application. Once installed, the "clone" command on the GitHub page will automatically start it to create a local clone of the repository. Most of the setups on the repository (e.g., setting the gh-pages branch) can be done from it (look at the "Branches" tab) without the command line tools.