W3C Usage of GitHub
A Recipe for writing W3C Standards
W3C on GitHub
- 326 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
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 repository
The repository manager will create a repository for you, as follows:
- LICENSE.md and CONTRIBUTING.md
- README.md
- Stub for index.html
- w3c.json
- Install hook for IP contribution tracking
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
Issue principles
- 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
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
-
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
- 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
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
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!
W3C Process
-
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?
Going forward
Improve the recipe: Share your tools, tips, and tricks