for W3C specifications
A Recipe for writing W3C Standards on GitHub
This Project Review is audio recorded
- Learn from each other on how to use GitHub for writing a specification
- Provide a forum for sharing tips and tricks on how to use GitHub efficiently
- Help groups to be more agile with the community by using GitHub
- Connect the workflow of GitHub, W3C Process, and W3C Patent Policy
- How to facilitate cross and wide reviews with Github
- How to reduce the gap between editor draft and /TR documents
- Harmonize the different ways W3C groups are using GitHub as much as possible
W3C on GitHub
- 311 repositories
- specifications, guidelines, documentation, command line tools, JS libraries, services, etc.
- 90 repositories were updated in November 2015
- 473 individuals
- 151 Teams
- editors, group participants, etc.
- Over 3100 open issues
- w3c/web-platform-tests is watched by 693 individuals
- 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
GitHub and the W3C Patent Policy
GitHub and W3C mailing lists
- Choose 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
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.
Set up your GitHub account
Set up your GitHub repository
The repository manager will create a repository for you, as follows:
- LICENSE.md and CONTRIBUTING.md
- Stub for index.html
- Install hook for IP contribution tracking
If you are already have commit history, see next slide
Get your team contact to create the repository as follows:
- Have only one branch gh-pages that contains your latest editor’s draft.
- Delete the master branch. Protect your main branch.
- Your document is visible at
- Your repository is associated with a GitHub team, who has write access
- Your repository and participants are known to the repository manager (cf contribution management)
One or several repositories?
- 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
Migrating from cvs or mercurial
- Plenty of tools are available out there for transforming between version control system
- Don't loose the history of your edits!
- Issues are no different from mailing list comments
- 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
- 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
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
- 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
Some issues are pertinent to other Groups. Should we use labels to help their wide review?
- security: affect the degree of resistance to, or protection from, harm of Web technologies
- privacy: affect the collection, processing and publication of personal data in Web technologies
- accessibility: affect the design of Web technologies for people with disabilities
- internationalization: affect the adaptation of Web technologies to different languages or regional differences
- architecture: affect the underlying principles that should be adhered to by all Web technologies
- performance: affect the download and display speed of Web technologies
- device independence: affect the ability of Web technologies to function on a wide variety of devices
- team review (eg @team-html-reviewers), similar to the ones used in web-platform-tests
- Pull requests are no different from mailing list contributions
- Avoid the “editor bottleneck”: Anyone is welcome to send a pull request to your repository so encourage especially all group participants to do so
- Master your pull requests like you master your issues (label, mentions, reference, individual support)
- Enable peer reviews so editors ought to use pull requests, like everyone else
- Don’t require a pull request to fix a simple typo and allow direct commits for those
- A substantive pull request should reference an issue, to facilitate managing issue tracking
Merging pull requests
- Merge pull requests as you close issues
- Consider squashing the commits to maintain a clean commit history for your specification
- Merge contributions from non-participants with care for IP reasons
Your GitHub 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
Using Git branches
- Ideally, the branch
gh-pages contains your latest editor’s draft.
- No need for the
master branch. The branch
gh-pages is the default one.
- GitHub team must create branches for the purpose of pull requests
- When creating a subset for the purpose of moving a specification forward, create a label and a dedicated branch for it. Label issues appropriately
Automatic Publication workflow
Pull requests allow for edits to be reviewed before being merged, so:
Your editor’s draft is really a Working Draft now
- You can use Travis integration to get W3C systems to publish your document
- Save time and set up Echidna as a Github hook
- 55 tokens in use, 200 Working Drafts were published since March through Echidna
- We're on IRC at
#pub for help
- Old pubrules tool retirement scheduled for August 2016
Automatic Publication workflow
When to publish?
- On every single commit/merge in the editor’s draft
- harder to track changes for outsiders
- travis can be used for this automation
- On every significant commit/merge (recommended by the W3C Process)
- harder to know when/remember to trigger the publication?
- 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!
- Wide review:
- use labels (see earlier)
- use “wide review” in your Working Draft SOTD to notify firstname.lastname@example.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?)
- agenda building?
- action items handling?
- activity summaries?
- Modern tooling
- @@more exploration of Gitter?
Improve the recipe: Share your tools, tips, and tricks
Things that might be useful as well