See also: IRC log
<plh> Slides are: http://www.w3.org/2015/Talks/1217-github-w3c/#/
<plh> (same ones as Google slides)
<Ian> scribenick: Ian
Presented by Philippe Le Hégaret
NOTE: This is being recorded by
... it will be made public
... if you do not wish to participate by audio.....don't speak up!
scribe: gaining experience
... want to show how relates to process and patent policy
... ultimately we'd like to harmonize how we use the tool across groups to make it easier to participate across groups
What is this NOT about?
PLH: large developer community
using it...makes sense for w3c community to use it as
... lots of tools (like post processing) available
Repository manager -> https://labs.w3.org/hatchery/ash-nazg/
help track contributions from non-participants
PLH: Reduce notifications to not be overwhelmed
<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)
Note about force
Protect your main branch.
<Ralph> Don't Use the Force
PLH: One or several repositories?
(pros and cons)
scribe: tools target 1 spec per rep
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]
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]
PLH: invite comments!
... easy to track
... advertize your repo
... group may accept them or not
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!
<AdrianHB> [... and therefor, as Ian says, uses the wiki on that repo]
PLH: Some groups allow closing by
individuals, some close after X days,
... pick a closure policy that matches your group size, culture
... make it as easy as possible to close typo fixes
<Ralph> [I interpret "allowed to close" and "can close" on the slide as "entitled to ..."
wide review / horizontal issues
PLH: My thinking is that we can use labels (e.g., "Security")
(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
... 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]
PLH: I prefer pull requests to
fix typos to email telling me to do so...just push a
... 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
<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
... 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 !
<dom> r12a, my script does html validation among other checks (both pre- and post-respec processing)
scribe: Merge pull requests as you close issues
PLH: Tip - Consider squashing the
commits to maintain a clean commit history for your
... 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]
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?
PLH: Ideally you use
... 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
... 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 original 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!
[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
PLH: regarding the wide review
requirement...suggest using labels
... also note use of firstname.lastname@example.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 126.96.36.199 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!
PLH: We don't yet have a
recommended way to generate a disposition of comments from an
... 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)
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
scribe: for example, there's a
tool called "gitter" that is a chat tool integrated with
... I don't know yet of any group that's decided to switch from IRC to bitter
PLH: If you are interested in a project review on details of using github (e.g., pull requests) or auto publishing, let me know.
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
... 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
<koalie> thanks Ian for scribing and plh for the review! bye all!