This article is a stub. You can help the W3C wiki by expanding it.
GitHub is one of several tools in use by W3C groups and participants.
What are best practices for use of Github in W3C efforts?
In Working Groups
See for example (and feel free to re-use for your own W3C groups!)
- See: http://www.w3.org/2015/Talks/1217-github-w3c (this information should be incorporated and updated here inline on the wiki)
ISSUE: We should find a mechanism to remind all people who show up at the Github repository for a W3C WG Spec that we want contributions from Members or Invited Experts. Participants who are not IEs or from Member organizations who would like to make contributions should explore joining or becoming an IE.
- Is there a policy document (or similar) covering the use of Github versus W3C-hosted version control? (and presumably technology preference is a factor in that, but not the only factor)
... add your question/issue here
- people involved in W3C Working Groups have W3C Account; having them using github require a separate GitHub account?
- A: Yes
- If a W3C group uses github as its basis of collaboration, participation in the group is subject to github's privacy policies etc. When is that a reasonable trade-off?
- Use of git itself is decentralized so participants can collaborate directly with peers as alternative to going through github. But facilities such as issue tracking and pull requests are not; they necessarily involve use of github's web site.
- we need infrastructure to use github to develop content, but have it published on a W3.org URI
- how do we ensure that we keep a log of the interactions that happen on github? (if only for historical purposes)
- A: a git repository would seem to suffice as its own log; for issues, there's an API. Presumably the API suffices for pull requests etc. as well.
- centralized interactions on w3.org services made it (somewhat) easier to search for particular items and topics; having these interactions spread across multiple uncoordinated github repositories makes it harder
- Is there a w3C tutorial page or guide to use Github
- on deploying specs using GH: http://tobie.github.io/specs-on-github/
- https://www.w3.org/wiki/Guide/GitHub gives some good practice
- https://github.com/w3c/csvw/blob/gh-pages/publishing_process.md gives a possible approach to combine github, respec, the W3C publishing process, with a reasonable trace of past versions all at the same place
Git recipes & tricks
I find these aliases handy (they save keystrokes). You can put them inside your configuration files.
alias.br=branch alias.cf=config alias.ci=commit alias.co=checkout alias.pl=pull alias.ps=push alias.re=remote alias.sh=stash alias.st=status
$ git ci
is equivalent to
$ git commit
Other useful config
branch.autosetuprebase=always(documentation): I find it easier to work with Git this way
push.default=simple(documentation): the default since Git 2.0; probably you don't need to set it
core.editor=emacs -nw(documentation): that's the editor that will be invoked every time Git needs to ask you about a commit message, when you're squashing commits, etc (and of course, you want emacs for that)
gpg.program=gpg2(documentation): you will need to set up these variables (and possibly a couple other) if you want to sign your commits to GitHub using GPG (recommended)
Safest way to “update” a local copy
I find this sequence of commands the “safest” way to quickly “refresh” a clone of some remote repo, and at the same time check its status (where “safest” means “reducing to the minimum the probability of messing up things with conflicts, outdated branches, uncommitted changes, etc”):
$ git branch -a $ git pull -r $ git status $ git remote prune origin --dry
$ git branch -adisplays information about all branches, both local and remote
$ git pull -rfetches changes from the remote and “rebases the current branch on top of the upstream branch after fetching”
$ git statusshows you the status of your copy: whether there are new files, missing files, unstaged changes, or commits pending push
$ git remote prune origin --drytells you if any branch in the remote has been recently removed (it will not remove it from your local copy automatically, but you can do that yourself if you see some branch is no longer necessary)
You can have those four lines as an alias, or inside a script somewhere.
Even better: if you set up the aliases suggested above, the whole thing becomes:
$ git br -a;git pl -r;git st;git re prune origin --dry
You can then type it and run it just once, and, from that moment on, simply recover the line from your shell history.
For example, if you're using Bash: press
r, then start typing a distinctive chunk of the line (eg,
st;gi); if you used it not too long ago for the last time, the entire line should appear, and you can simply press
An alias to view the history of the repo
alias.lg=log --graph --abbrev-commit --decorate --date=relative --format=format:'%C(bold blue)%h%C(reset) - %C(bold green)(%ar)%C(reset) %C(white)%s%C(reset) %C(dim white)- %an%C(reset)%C(bold yellow)%d%C(reset)' --all
Then, simply type
$ git lg
for a colourful graph of commits, tags and branches.
- https://github.com/w3c/ash-nazg - tool to enable non-WG members to make contributions to W3C specs
- in progress Guide for using GitHub for W3C spec work (issues)