Skip to content

How the Working Group works

ianbjacobs edited this page Apr 7, 2016 · 59 revisions

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

NOTE: Ian Jacobs updated this information on 5 April 2016 and plans to socialize with the WG at the 7 April 2016 teleconference.

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:

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 public-payments-wg@w3.org (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 member-payments-wg@w3.org internal administrative matters.
  • The Working Group receives public comments on public-payments-wg@w3.org.

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 specifications

  • We recommend forking the specification, making changes in your fork, then making pull requests.
  • The Editors will merge uncontroversial pull requests without further group discussion.
  • For substantive change requests, or ones that address issues, the Working Group will discuss the proposals before they are merged.

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 taken up the specification.
  • Once the group has taken up the specification, we will create a repo for the new specification.

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

Use of GitHub:

  • We mark issue priority via a Milestone (low, medium, or high priority).

Issue States

  • Raised: A Working Group participant has raised an issue 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.
  • In Progress: 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, in which case the issue moves back to the "Raised" state.

Use of GitHub:

  • "Open" and "Closed" are GitHub issue states.
  • "In Progress" is determined by the presence of a proposal associated with the issue (e.g., unmerged pull request).
  • "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 (multi-colored) labels to categorize issues by topic (e.g., security or extensibility). These labels are primarily used to help with prioritization.

Postponed Features

  • From time to time the group will resolve not to include a feature in the current version of a specification.

Use of GitHub:

  • "PostponedFeature": Used to label issues related to postponed features. (We should not say "v2" as that is unnecessarily specific.)

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.
Clone this wiki locally