From W3C Wiki
Jump to: navigation, search

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.


Best Practices

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!)

In General

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.

Other issues

  • 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 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 services made it (somewhat) easier to search for particular items and topics; having these interactions spread across multiple uncoordinated github repositories makes it harder

Git recipes & tricks

Useful aliases

I find these aliases handy (they save keystrokes). You can put them inside your configuration files.

With these,

$ 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)
  • commit.gpgsign=true (documentation) and 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 -a displays information about all branches, both local and remote
  • $ git pull -r fetches changes from the remote and “rebases the current branch on top of the upstream branch after fetching”
  • $ git status shows you the status of your copy: whether there are new files, missing files, unstaged changes, or commits pending push
  • $ git remote prune origin --dry tells 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 Ctrl+r, then start typing a distinctive chunk of the line (eg, r;, or st;gi); if you used it not too long ago for the last time, the entire line should appear, and you can simply press Enter.

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.

See Also