How the Working Group works - w3c/webpayments GitHub Wiki

This is documentation of the (evolving) practices of the Web Payments Working Group.

Ways to contribute

We encourage participants to contribute and there are many ways to do so, including:

  • Review specifications and raise issues.
  • Write proposals to address issues
  • Author specifications (e.g., payment method specifications)
  • Implement the group's technical work
  • Contribute to the (soon-to-exist) test suite
  • Help communicate the group's work (e.g., via developer documentation, visuals, slide decks, etc.)
  • Raise awareness in other fora about the group's work.

Decisions

GitHub

The Working Group manages issues and specifications on GitHub in multiple repositories (listed in the right navigation of this page).

To learn more about using GitHub:

If you have questions about the use of GitHub or require access rights, please contact the Chairs or Team Contacts.

Mailing Lists

  • The Working Group's primary mailing list is [email protected] (archive).
  • The list is used for important communications such as meeting agendas, discussions of topics not yet in GitHub, and calls for consensus around proposals. People may use the list to raise issues, although it is preferred to use GitHub directly.
  • The Working Group uses [email protected] internal administrative matters.
  • The Working Group receives public comments on [email protected].

Meetings

See Meetings.

Wiki

  • Group participants are invited to create new pages in the group's main wiki.
  • When you add a page that you consider important, notify the Working Group on public-payments-wg.
  • It is also helpful to have important pages linked from other frequently viewed pages; please work with the Chairs and Team Contacts on where to include those links.

Specifications

Proposing changes to existing Editors' Drafts

  • We recommend forking the specification, making changes in your fork, then making pull requests.

On Editors Incorporating Changes and Updating TR documents

  • At the 14 April 2016 teleconference the Working Group adopted the following process for updating TR specifications:
    • Editors may incorporate proposals that reflect consensus, and changes for editorial and bug fixes, without an explicit group decision. Editors will use their best judgment when assessing consensus (e.g., strong support and no objections to a proposal on GitHub).
    • On topics or proposals where there is not yet consensus, the Working Group Chairs will organize discussion and a decision prior to changes being incorporated by the Editors.
    • The Working Group resolved to adopt auto-publishing: Editor's drafts will be pushed to the TR page when the Editors' drafts change.

Creating New Specifications

  • We use ReSpec as the source format for specifications.
  • If you wish to create a new specification, please use the "Proposals" folder of the group's main repo until the group has decided to take up the specification.
  • Once the group has taken up the specification, we will create a repo for the new specification.

Preparing specifications

  • Use rawgit (with same path to GitHub repo for spec minus the "blob" piece of the path) or ghpages version with pubrules.

Issues and Actions

Many important Working Group decisions follow from issues that are raised about deliverables. The following describes general expectations about issue management.

High Level View of Issue Management

At a high-level, issues, actions, and decisions frequently relate as follows:

  • A participant raises an issue (e.g., on GitHub or via the mailing list). Where possible, the participant should include a concrete proposal for how to address the issue.
  • The Chairs are responsible for prioritizing issues and seeking consensus resolutions. This is often done by assigning action items to people to create proposals for addressing the issue. Generally participants are encouraged to submit proposals as GitHub pull requests.
  • Those proposals are reviewed by the Working Group (by email and during meetings); this may lead to revisions.
  • When there is a decision to adopt a proposal, the issue is closed.
  • If a decision involves edits to a Working Group deliverable, the Editors will be responsible for incorporating the changes.

Prioritization

  • The Chairs are responsible for prioritizing issues activities of the participants (e.g., Editors, test suite contributors, etc.). The Chairs do this by soliciting input from the Working Group.
  • Issue priority reflects a variety of considerations, including:
    • Whether other issues depend on its resolution
    • Whether it is blocking implementations.
  • Low priority issues are "back burner" issues and discussion will not likely be encouraged until higher-priority issues have been addressed.
  • People may petition the chairs to change the prioritization of issues.

Use of GitHub:

Issue States

  • question: A Working Group participant has raised an question and there is not yet a proposal to address the issue. One way to make progress on an issue is to assign an action (with a deadline) to a participant to write a proposal to address the issue.
  • help wanted: The chairs are looking for someone to make a concrete proposal to address the issue.
  • proposal - needs discussion: There is one or more proposal to resolve the issue, for consideration by the Working Group.
  • closed: The Chairs have closed the issue and no further discussion is anticipated unless there is new information. An issue may be closed for diverse reasons, including reaching a decision, indicating that the issue has been subsumed by another issue, or because the person who raised it wishes to close it without further discussion. Chairs may reopen a closed issue when presented with compelling new information.

Use of GitHub:

  • "Open" and "Closed" are GitHub issue states.
  • "Milestones": label used in conjunction with action item due dates

Categorization

Beyond tracking the state of an issue, the group uses GitHub labels for other categorization:

  • To indicate or determine which document an issue refers to, look for the current set of labels that include the "Doc:" prefix.
  • The Working Group is also using labels to categorize issues by topic (e.g., design or extensibility). These labels are primarily used to help with prioritization. These labels use the prefix "Cat:"
  • Issues that should be considered as part of a horizontal review for wider topics like security, privacy, accessibility etc are marked with an "HR:*" label.

Postponed Features

  • From time to time the group will resolve not to include a feature in the current version of a specification; see the List of postponed features

Issue Markers in Specifications

From Chair email about issue markers:

  • When an issue is relevant to a specification and there is no proposal in the specification, we will include an issue marker.
  • When an issue is relevant to a specification and there is corresponding text in the specification, we will include an issue marker only for the purpose of drawing attention to a specific part of the text. We will not include an issue marker using general text with a comments or question about potential alternatives. (Discussion should continue on the GitHub issues list until there are concrete proposals.)
  • When an issue is not relevant to a specification, we will not include an issue marker in that specification.
  • Whether or not an issue is relevant to a specification, when there are concerns that the topic is out of scope for the Working Group, we will not include an issue marker in a specification until the Working Group has made a decision on the scope. This is to reduce the breadth of organizations' patent policy reviews until there is a decision from the Working Group.

Communications

IRC

  • The group's primary channel is #wpwg on irc.w3.org