GitHub etiquette

GitHub layout

This workflow relates to material managed in the github repository https://github.com/w3c/dxwg The repository owner (Dave Raggett) will add members of the WG when they supply their GH id.

The default branch is gh-pages https://github.com/w3c/dxwg/tree/gh-pages (as the main working group deliverables are documents)

The repository has a directory for each deliverable, so far

• https://github.com/w3c/dxwg/tree/gh-pages/AP
• https://github.com/w3c/dxwg/tree/gh-pages/dcat
• https://github.com/w3c/dxwg/tree/gh-pages/ucr

Normative artefacts related to the working group deliverables are

1. HTML documents which are intended to become Recommendations, Notes or other formal web-page deliverables
2. RDF files
3. possibly some other code

Contributing to the normative deliverables

Everyone who has permission to push to the DXWG GitHub repository could make changes on any branch including the head. So in order to ensure an orderly process, we need to all follow some ground rules about who can make changes where and when. The main principle is that only editors are allowed to make changes to the normative artefacts (HTML documents, RDF files) in the head branch (gh-pages). That means

• only Ixchel, Jaroslav, Rob for ucr/index.html
• only Alejandra, Dave, Simon, Peter for dcat/index.html and dcat/rdf/dcat.ttl etc
• only Ruben, Lars, Rob for profiles/index.html
• only Rob and Nick for profiledesc/profiledesc.html and profiledesc/profiledesc.ttl etc (though unclear if this is a normative deliverable yet)

Every WG member can use the other collaboration spaces to work towards consensus on particular topics, in particular GitHub issues, the GitHub Wiki, and of course the Mailing List. But the consensus must be reflected up into the normative artefacts in order to stick.

Thus, the basic workflow is

1. reach consensus on a topic, and ensure that evidence of consensus is recorded in either a GitHub issue of the mailing list, or through a resolution in a meeting
2. make changes to the normative artefacts reflecting the consensus, on a github branch created for that topic;
3. create a pull-request of your branch into the head branch (i.e. gh-pages), nominate a reviewer, and assign the PR to the editors for that deliverable to merge the changes into gh-pages [1].

Note that, if it is an editor making changes, then their immediate role is as a working group member, and a different editor should be asked to review and accept the changes.

Since this rule is not enforced by the GitHub permissions, it relies on everyone behaving themselves.

GitHub workflow

The recommended workflow to make a change (edit) to a deliverable

1. Make a clone of https://github.com/w3c/dxwg.git for your work in your local environment.

2. Create a Git branch for the change or set of related changes in the clone, and give it a helpful name

• e.g. 'dcat-type-vocabulary-simon'

Work on one set of related changes on the normative artefacts related to only one deliverable (i.e. UCR vs DCAT vs Application Profiles ...) in this branch

3. Periodically push the local branch back to a branch in the origin with the same name

• e.g. https://github.com/w3c/dxwg/tree/dcat-type-vocabulary-simon

Also make sure to merge any subsequent changes that have been accepted in the gh-pages branch into the branch, so that your branch doesn't diverge from the main branch except for the topic you are working on.

4. When the change is ready for review, first ensure that it has no conflicts with gh-pages (because you've done all the necessary merging from gh-pages) then create a pull request to merge the branch into the head (i.e. gh-pages). Assign it to one of the editors for the deliverable (e.g. AP, dcat, ucr). Also link it to all related issues from https://github.com/w3c/dxwg/issues

Then in response:

5. The editor(s) assigned to the pull-request reviews the pull request (proposed change), and either accepts the request and merges the proposed change into the deliverable, or opens a discussion, by adding comments to the pull request, until resolved.

6. If the pull-request has been accepted, then it is recommended to delete the branch, so that the repository does not get too cluttered!

[1] It might be acceptable to bend the rules for 'typos' but the boundary can be a bit grey, so it may be simpler to apply the rule to all changes and just ask contributors to mention when they think the change is just a typo so that the editor can process it quickly.

Raising issues

Use GitHub issue tracker.

New use-cases should be submitted as GitHub issues, using markdown template (to be) provided by Dave Raggett.