Using GitHub for W3C specifications (original) (raw)

A Recipe for writing W3C Standards on GitHub

Disclaimer

This Project Review is audio recorded

Goals

• 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

What is this NOT about?

• How to use Git?
• An introduction to GitHub
• Editor tools: respec, bikeshed, etc.
• Automatic /TR publication issues
• etc.

xkcd.com

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

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 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 courtersy of Charles McCathieNeville

One can use branches and labels for specification versioning.

GitHub and the W3C Patent Policy

• Anyone can make a contribution, but only Group members committed to Royalty-Free
• Install proper license and contribution files in your repository
• Remember How should Working Groups handle contributions from non-participants?
• We have a repository manager to help and track contributions

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

GitHub: got questions?

• Most of our tools are developed on GitHub
• Documentation is at w3c.github.io (repository)
• We’re hanging on IRC #git for help
• spec-prod@w3.org

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

• Configure your notifications:
  • deactivate automatic watching
  • pick email and/or web notifications
• Set up two-factor authentification
• Watch specific repositories
• Manage your assigned issues
• If you picked email notification, filter the emails for your own sake
  (
  From:notifications@github.com, To:w3c/
  )

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

If you are already have commit history, see next slide

Using gh-pages?

Get your team contact to create the repository as follows:

• Use https://github.com/w3c/<shortname>
• 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 https://w3c.github.io/<shortname>/
• 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!

Issue principles

1. Issues 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

• 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

Horizontal issues?

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

1. 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

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

xkcd.com

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?

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

• Wide review:
  • use labels (see earlier)
  • 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

• 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
• Proposal for follow up Project Reviews?

Extra slides

Things that might be useful as well

Git commands

• Got 15 minutes and want to learn Git?
• Git clients
• GitHub tool
• git add -p for fine-grain commits
• For your .gitrc:
  [alias]
  pr = !git fetch -fu 2:−originrefs/pull/{2:-origin} refs/pull/2:−originrefs/pull/1/head:pr/$1 && :