W3C Usage of GitHub

A Recipe for writing W3C Standards

W3C logo GitHub logo

W3C on GitHub

  • Tree blooming326 repositories
    • specifications, guidelines, documentation, command line tools, JS libraries, services, etc.
    • 90 repositories were updated in November 2015
  • 515 individuals
  • 162 Teams
    • editors, group participants, etc.
  • Over 3100 open issues

Why GitHub?

  • Web-based graphical interface for the Git decentralized version control system
  • Provides access control
  • Hub: Allow easier collaboration from a wider community:
    • Issue tracking tool with edit patch support
    • Continued integration of tooling (travis, …)
    • Facilitate peer reviews
  • Harmonize as much as possible the group workflow
XKCD 1597: illustration of Git
xkcd.com

GitHub and the W3C Process

The use of GitHub doesn’t change the W3C Recommendation track:

Flowchart: Process for producing a W3C Recommendation First Public Working Draft - Exclusion Opportunity First WD WG Decision Director's approval Working Draft WD Publish a New Working Draft WG Decision: review needed, or No change for 6 months Advance to Candidate Recommendation Director's approval Candidate recommendation - Patent Policy Exclusion Opportunity CR Publish a revised CR Working Group Decision, Directors approval for substantive changes Advance to Proposed Recommendation Director's approval Return to Working Draft WG or Director decision e.g. for further review Proposed Recommendation - Advisory Committee Review PR Advance to Recommendation Advisory Committee Review Director's Decision Return to Working Draft AC Review, Director Decision e.g. for minor changes Return to Working Draft Advisory Committee review and Director's Decision, e.g. for further work and review W3C Recommendation REC Proposed change to a Recommendation Changes to text? No text changes: Edited Recommendation No Director'sapproval Yes Substantive changes? No substantive changes: Proposed Edited Recommendation No Director'sapproval Yes New Features? No new features - return to Candidate Recommendation No Director'sapproval Yes
Illustration courtesy of Charles McCathieNeville
One can use branches and labels for specification versioning.

GitHub and
the W3C Patent Policy

Patent illustration from the 1888 Eastman camera patent

GitHub and W3C mailing lists

  • Postman struggling with bag full of mail lettersChoose where issues get discussed: in GitHub or in the mailing list?
  • In GitHub:
    • Easier tracking
    • Issue can have associated patch for the specification (pull request)
  • In mailing list:
    • permit the use of email client (threading, …)
  • Tool to facilitate integration: github-notify-ml

GitHub: got questions?

How to GitHub

  • We’re building recipes and tools
  • Depending on your editor(s), Group, your specification, and community, different settings/approach may be appropriate.
  • Feel free to adapt the recipe to your need.
XCKD 1296: As a Project Drags on, my Git commit messages get less and less informative
xkcd.com

Set up your GitHub repository

The repository manager will create a repository for you, as follows:

  • Picture of a car being tunedLICENSE.md and CONTRIBUTING.md
  • README.md
  • Stub for index.html
  • w3c.json
  • Install hook for IP contribution tracking

One or several repositories?

  • To be or not to be character One specification per repository:
    • easier to watch/hook per specification
    • no need to label issues or pull requests
    • global understanding of status requires additional tooling
    • greater tooling integration in the long run
    • harder to move materials between specifications
  • One repository for the Group:
    • easier to move materials between specifications
    • one issue list for all of your specifications
    • inadequate integration with our tooling in the long run

Issue principles

  1. Individuals raising their hands under the earth globeIssues are no different from mailing list comments
  2. Anyone should be welcome to raise an issue in your repository, so don’t be shy and advertize your repository and issues list in your document
  3. Anyone should be welcome to propose a resolution to address an issue, but your group is responsible to ensure that it gets resolved one way or another

Mastering issues

Learn to master your issues:

  • Use labels to differentiate between bugs, enhancement, etc.
  • Assign issues to individuals
  • Use @mentions to involve individuals
  • Use references inside of issues and pull request
  • Facilitate Group decisions by encouraging individuals to support resolutions :+1:
  • Keep your issues up-to-date: copy issues from other sources (eg mailing list) to GitHub
  • Use a dashboard to keep track of all your repository issues

Closing issues

  • Graphic showing that open issues grow faster than closing issue Different policies:
    • Anyone in the GitHub team is allowed to close an issue if critical support was met
    • or, only editors/chairs can close issues
  • Critical support is reached depending on how decisions are made in your Group
  • Save time and make it easy to make decisions for:
    • editorial issues
    • substantive issues that gathered general support on GitHub

Pull Requests

  1. Cartoon character crying and saying: "My Pull Request, please merge it"Pull requests are no different from mailing list contributions
  2. Avoid the “editor bottleneck”: Anyone is welcome to send a pull request to your repository so encourage especially all group participants to do so
  3. Master your pull requests like you master your issues (label, mentions, reference, individual support)
  4. Enable peer reviews so editors ought to use pull requests, like everyone else
  5. Don’t require a pull request to fix a simple typo and allow direct commits for those
  6. A substantive pull request should reference an issue, to facilitate managing issue tracking

Your GitHub awesome team

  • Your GitHub team has push/write access to the repositories
  • Avoid creating second class citizens and empower all Group participants to be in your GitHub team
  • or, Put editors in your team
  • Avoid misunderstandings: make sure to document your issues and pull requests workflow and the conditions to close those
A team of lego characters from the Lego movie

Automatic Publication workflow

When to publish?

  1. On every single commit/merge in the editor’s draft
    • harder to track changes for outsiders
    • travis can be used for this automation
  2. On every significant commit/merge (recommended by the W3C Process)
    • harder to know when/remember to trigger the publication?
  3. On demand (dedicated separate branch?)
    • High risk for having an outdated /TR document

Make your Group decision to publish as you see fit but, please, don’t let 6 months elapse!

W3C Process

  • Chutes and Ladder Game Wide review:
    • use labels
    • use “wide review” in your Working Draft SOTD to notify public-review-announce@w3.org
  • Use pull requests to review proposals and get consensus
    • if that fails, you may need some teleconference/whiteboard time to resolve the differences
  • Use branches for versioning
  • No recommended way to have disposition of comments for the Director (labels?)

Additional tooling

  • agenda building?
  • action items handling?
  • activity summaries?
  • Modern tooling
  • @@more exploration of Gitter?
Work tools

Going forward

Improve the recipe: Share your tools, tips, and tricks

  • Got a tool in your Group? We’d love to be aware of it.
  • Documentation is at w3c.github.io
    (repository)
  • We’re hanging on IRC #git for help
  • spec-prod@w3.org
  • Pre-TPAC session for GitHub newbies?
Sailors rowing