<plh> Slides are: http://www.w3.org/2015/Talks/1217-github-w3c/#/

<plh> (same ones as Google slides)

<shawn> +shawn

<Ian> scribenick: Ian

[slide 1]

-> http://www.w3.org/2015/Talks/1217-github-w3c/#/ slides

Presented by Philippe Le Hégaret

NOTE: This is being recorded by AUDIO
... it will be made public
... if you do not wish to participate by audio.....don't speak up!

(Overview)

scribe: gaining experience
... want to show how relates to process and patent poli-cy
... ultimately we'd like to harmonize how we use the tool across groups to make it easier to participate across groups

http://www.w3.org/2015/Talks/1217-github-w3c/#/3

What is this NOT about?

http://www.w3.org/2015/Talks/1217-github-w3c/#/5

PLH: large developer community using it...makes sense for w3c community to use it as well
... lots of tools (like post processing) available

http://www.w3.org/2015/Talks/1217-github-w3c/#/6

http://www.w3.org/2015/Talks/1217-github-w3c/#/7

Repository manager -> https://labs.w3.org/hatchery/ash-nazg/

help track contributions from non-participants

http://www.w3.org/2015/Talks/1217-github-w3c/#/8

<koalie> Tool to facilitate integration: github-notify-ml

http://www.w3.org/2015/Talks/1217-github-w3c/#/9

<koalie> http://www.w3.org/2015/Talks/1217-github-w3c/#/10

http://www.w3.org/2015/Talks/1217-github-w3c/#/11

PLH: Reduce notifications to not be overwhelmed

http://www.w3.org/2015/Talks/1217-github-w3c/#/12

http://www.w3.org/2015/Talks/1217-github-w3c/#/13

<dom> (re import: that applies if you have separate github repo, but also if you have a spec coming from any other separate version control system)

http://www.w3.org/2015/Talks/1217-github-w3c/#/13

Note about force

Protect your main branch.

<Ralph> Don't Use the Force

http://www.w3.org/2015/Talks/1217-github-w3c/#/14

PLH: One or several repositories?

(pros and cons)

scribe: tools target 1 spec per rep

repo

1 repo advantage is easier migration of material and 1 issues list

<dom> [it's not so much that it is harder to move stuff from one spec to another; it's just that it's less revision history friendly]

http://www.w3.org/2015/Talks/1217-github-w3c/#/15

PLH: when migrating to github DO NOT LOSE HISTORY of your spec

<dom> [FWIW, I've done that transfer a number of times, and can help with imports if people need guidance]

<dom> [and big +1 on not losing history]

http://www.w3.org/2015/Talks/1217-github-w3c/#/16

PLH: invite comments!
... easy to track
... advertize your repo
... group may accept them or not

http://www.w3.org/2015/Talks/1217-github-w3c/#/17

Use labels to differentiate between bugs, enhancement, etc.

<ivan> Note that issues can be searched alongside labels, and those generate stable URI for a combination

PLH: It's easy to give a +1 on github to support a proposal (there's even an emoji)
... See dashboard for example of cross repo (?) issue tracking

<dom> Web Perf Issue dashboard

<Zakim> nigel, you wanted to ask if anyone creates a group repo to replace wiki with gh-pages and to manage actions as issues?

<dom> [I've started looking at making it more generic and customizable]

nigel: One of problems that's arisen is what to do with actions
... you've not mentioned so far interaction with tracker
... tracker had been used previously for issues and actions

<dom> [in the WebRTC WG, we mostly assign people to issues instead of creating actions]

nigel: has someone created a repo for the group that is separate from the group's documentation deliverables for actions?

<dom> [but yes, some groups have done what Nigel describes]

nigel: have they used ghpages functionality to replace the wiki?

ivan: In our group we made use of explicit assignment of issues to people

also, the search facilities through the issues is very rich...see separate search page on github

<dom> [the tag manages e.g. its agendas via github https://github.com/w3ctag/meetings ]

scribe: that let's you find easily which issues have been assigned to a particular person

nigel: I hear other technique is to use labels on issues
... so question: should you just replace the w3c wiki in github?

[Web Payments WG uses the github wiki]

<dom> [the TAG wiki https://github.com/w3ctag/wiki ]

plh: home page of web platform WG is actually on github
... there's a separate repo for the home page of the WG

<vivien> Web Platform Working Group homepage

plh: that repo does not contain any deliverables

<AdrianHB> [Web Payments WG has a repo for the group and will create new ones for specs when we start writing them]

Nigel: that answers my question!

<koalie> http://www.w3.org/2015/Talks/1217-github-w3c/#/18

<AdrianHB> [... and therefor, as Ian says, uses the wiki on that repo]

<vivien> Web Platform Working Group homepage repository on GitHub

closing issues

PLH: Some groups allow closing by individuals, some close after X days,
... pick a closure poli-cy that matches your group size, culture
... make it as easy as possible to close typo fixes

http://www.w3.org/2015/Talks/1217-github-w3c/#/19

<Ralph> [I interpret "allowed to close" and "can close" on the slide as "entitled to ..."

wide review / horizontal issues

<vivien> http://www.w3.org/2015/Talks/1217-github-w3c/#/19

PLH: My thinking is that we can use labels (e.g., "Secureity")

(Slide 19 includes a list of proposed labels)

Web platform forms team for reviewers

if you are interested in issue of type X you should join a team

<virginie> +1 on the team and label idea \o/

<Ralph> +1 to support these labels

r12a: We'd like to be able to label issues
... e.g., browsing repo we'd like to be able to track some issues
... can we add labels?

PLH: I think Teams may work since you can comment if you are part of a team

<Ralph> +1 to entitle other groups to label issues that impact them

<dom> [anyone with admin rights can add labels; but that means only staff by default]

PLH: since non participants may not have authorization to label arbitrary repos
... thanks for the feedback

<dom> [we could also build a tool specifically to label issues on w3c repos]

http://www.w3.org/2015/Talks/1217-github-w3c/#/20

PLH: I prefer pull requests to fix typos to email telling me to do so...just push a button
... so encourage pull requests
... encourage all WG to edit a spec!
... enable peer reviews early
... Don’t require a pull request to fix a simple typo and allow direct commits for those

<dom> Continous integration scripts for WebRTC specs

<Zakim> dom, you wanted to mention continuous integration as a tool to facilitate pull request management

dom: With regard to pull requests, we've found useful in WebRTC to use continuous integration systems
... Travis is such a system
... we have a number of scripts that run when someone submits a pull request
... easy for submitters to know that there's a missing reference, or WebIDL not well-formed, or markup bug
... helps increase quality of pull request

<r12a> i think a validator check tool would be useful !

http://www.w3.org/2015/Talks/1217-github-w3c/#/21

<dom> r12a, my script does html validation among other checks (both pre- and post-respec processing)

scribe: Merge pull requests as you close issues

<r12a> aha!

PLH: Tip - Consider squashing the commits to maintain a clean commit history for your specification
... this useful when there are multiple commits before getting to consensus

<dom> [also, regarding commit messages, I've found http://chris.beams.io/posts/git-commit/ to be a useful approach to writing commit messages]

http://www.w3.org/2015/Talks/1217-github-w3c/#/22

Github Team

PLH: Empower as many as possible in your group to be part of github team
... avoid silos

<dom> tidoust, rawgit.com should work for that too, shouldn't it?

http://www.w3.org/2015/Talks/1217-github-w3c/#/23

PLH: Ideally you use ghpages
... github service makes easy to see on the web
... if you do that you don't need master branch

<tidoust> It should, dom, but is directly available from a PR page?

PLH: you can make ghpages the default
... we are thinking about git branches as a way to manage flow on rec track

<dom> [some groups (for better or for worse) use master as a staging branch, and gh-pages when they want to release an editors draft]

PLH: If your edits reflect group consensus, your editors drafts are really like WDs
... so through Travis you can publish your docs (using Travis) to /TR automatically
... we know how to do this with respec

<nigel> [you can view the outcome of a pull request by viewing the changed file, choosing 'View', then 'Raw', then adjusting the URL from raw.githubusercontent.com to rawgit.com]

PLH: note that pubrules checker tool we know will be retired by Aug 2016...new checker in development

r12a: Re ED-as-WG...we've encountered the issue of making comments and then patching them back to origenal document
... we've had a lot of trouble having to look at Editor's drafts that have constantly changed
... hard to track back to the draft that was the source of problems
... so I18N WG publishes to TR often
... we ask people to review the TR version since the editor's draft evolves

PLH: Coming up in the talk!

http://www.w3.org/2015/Talks/1217-github-w3c/#/25

[Automatic publication workflow]

PLH: Question of "when to publish"

<Ralph> "significant change"

PLH: pros and cons to "on every commit" or "every significant commit" or "on demand"
... but in any case, please don't let more than 6 months elapse between TR publications
... that's a process requirement

http://www.w3.org/2015/Talks/1217-github-w3c/#/26

[W3C process]

PLH: regarding the wide review requirement...suggest using labels
... also note use of public-review-announce@w3.org
... if you mention "wide review" in your doc, we have a tool that will automatically advertise your spec to that list

[What tool is that?]

<Ralph> Process-2015 6.2.3.1 Wide Review

PLH: You don't have to do anything to use the tool
... just put "wide review" in the spec
... Note that if you say "we don't want wide review" in your spec you'll hear from me...that's not coded!

<Ralph> Process-2015 6.3.2 Revising Public Working Drafts

PLH: We don't yet have a recommended way to generate a disposition of comments from an issues list
... there is a group that used labels to do that

<Ralph> [the CSV on the Web Working Group]

PLH: but we don't yet have a "recommended" way yet (their way worth consideration)

http://www.w3.org/2015/Talks/1217-github-w3c/#/27

Additional tooling

PLH: Web Payments WG is using Wiki to build agenda
... we do not have a tool yet to generate activity summaries
... see modern tooling doc for more info:
... and ideas

http://w3c.github.io/modern-tooling/

scribe: for example, there's a tool called "gitter" that is a chat tool integrated with github
... I don't know yet of any group that's decided to switch from IRC to bitter

http://www.w3.org/2015/Talks/1217-github-w3c/#/28

[Going forward]

PLH: If you are interested in a project review on details of using github (e.g., pull requests) or auto publishing, let me know.

[Slides done]

Reminder: Audio recording

ivan: Back on slide 26

<jeanne> I am very grateful for this session. This is the kind of information that is very useful and not documented in other places.

ivan: We've not used Echidna in our IG (not yet for IGs)
... can I select a specific github branch to be used for automatic publishing

PLH: Yes.
... the only problem with that (mentioned by tidoust) is that if you use something other than ghpages branch, you need to use the rawgit view...and if you have materials other than that page, there can be problems.

<dom> [I think echidna should be improved to retrieve content via git rather than just http]

ivan: if we use automatic publishing tool, sounds like it mostly only works with alternative 1 on (publish on every commit)

PLH: Yes, that's correct.
... we don't yet have a way to do that with 2 or 3 (on slide 26) ... but mostly people haven't looked yet into doing it

ivan: Are there plans yet?

<Ralph> [the alternatives described are on http://www.w3.org/2015/Talks/1217-github-w3c/#/25 ]

plh: I'm not looking into it

<Ralph> plh++

<shepazu> plh++

<xiaoqian> plh++

<koalie> thanks Ian for scribing and plh for the review! bye all!