Tooling Policy Discussions Page

We use a variety of tools both for the development of deliverables (e.g. Github, Bikeshed, ReSpec etc.) and for the operation of the W3C (e.g. Webex, IRC, the bots). A number of groups are experimenting with other tools as well (Slack, Converse, WebRTC and other call-in and conference systems), and we have some volunteer tools (ReSpec was one once, and the Github-bot comes to mind). We need to delineate the principles that apply; what tools can groups use, that have suitable accessibility (both for international audiences, and in the traditional sense), transparency, longevity etc. We have some obvious long-standing problems (calendaring is one). We also have a discoverability question: if one is not a member of a WG but wants to investigate something, or help on a topic, can you find where conversations occur, decisions are made, calls happen, etc. — and where the records of such are kept?

Groups at the W3C have discussions, and make decisions. Those discussions and decision can be at face to face meetings, in teleconferences, or asynchronous and online. It is important that all W3C members be able to check on the status of a group — what are they discussing, what have they decided — or join a group in flight, either for a short period (for some special concern that they have, for example) or for an indefinite period. Joining should not cause a long period of "getting up to speed".

These tools used to be fairly uniform across W3C groups: telephone conferences hosted by Zakim, IRC and the IRC bots, tracker for issues and actions, email for asynchronous communication, wikis for exploring ideas.

Community considerations

Backups and archives
Support and integration
Being able to operate as a W3C member; navigating around, finding resources, dropping in on unfamiliar workgroups
Tracing and following influence/comments and 'contributions'
Balancing improvement/modernization/experimentation with familiarity, navigability, ease-of-use

External tools

International considerations: language and script; firewalls and blocks; data-rate and bottlenecks (e.g. videophone over slow networks)
Accessibility considerations
Policy and user-agreement considerations, what can we ask members to agree to?

Areas of operation

Tools needed to be in, and operate, W3C groups (discussion, establishing consensus, calls, queues, minutes, …)
Tools used to develop W3C deliverables (history maintenance, filing issues/bugs/enhancement-requests, notifications, spec tools such as Bikeshed and Respec, pub. tools such as Echidna and validation; the mental schism between the development and publication locations; the mental model of delivering on 'virtual paper')

Internal tools

Inventory management: do we even know what's in use (call software—webex, zoom, bluejeans, WebRTC-tools, POTS, etc.). Link to 'how to use' (e.g. W3C Github)
Maintenance and support issues
The bots (zakim, trackbot, etc.)
Web site, internal and public-facing
Wikis
Team tools and volunteer tools
Internally-run externally-developed tools (SVN, Gitlab?, etc.?)?

Gap analysis

What do we need that we lack? (Dashboard, better Git integration, better maintenance and issue/errata tracking and integration with publishing, bots, calls)

W3C Tooling Policy DRAFT

This was an initial draft policy for tooling used for spec development at W3C. It has been superseded by Tooling Policy

Requirements

In order to maintain the openness and transparency of W3C's standards process, all tools used by Working Groups in the development of any W3C technical report must be:

Usable and accessible by all current members of the Working Group, regardless of location, disability, or (within reason) employer policy.
Have archives, including version history, which are fully publicly-accessible or Member-accessible (as appropriate) now and into the far future, for as long as W3C itself should exist.
Allow for public participation (such as providing feedback) where appropriate, again regardless of location or disability.

To effect this concretely, W3C requires that:

Any publication or deliverable of the Working Group that is intended for broad public consumption be available at a w3.org URL, thus insulating it from the demise or decommissioning of any service that W3C cannot itself maintain.
An archive of any publications, recorded discussions, source repositories, or other deliverables or development records be maintained on W3C servers, so that W3C's products and the logic that led to them can be accessed and understood by future maintainers and users.

The goal of this policy is to ensure that

All current and future members of the Working Group, and any successor to the Working Group can follow, fully participate in, and understand the discussions of the Working Group and the development of its technical reports.
W3C Members and/or the general public, now and into the far the future (for as long as W3C shall exist and beyond), can follow and understand the discussions of the Working Group and the development of its technical reports.

Examples

Specific W3C-maintained systems which satisfy these constraints include:

W3C's main web server its subsystems such as blogs, wikis, bug trackers, etc.
W3C Mailing Lists
IRC channels recorded to w3.org by RRSAgent or some other bot.

Specific externally-hosted systems which can be set up to satisfy these constraints include:

Externally-hosted DVCS repositories such as GitHub when they are set up for backup by W3C's systeam
Externally-hosted issue repositories such as GitHub when they are backed up by cross-posting to an archived W3C Mailing list

Examples of systems which do not satisfy these constraints include:

Google Docs, when their contents are not copied into a W3C-archived system for future reference or when the Working Group includes Members whose country blocks access to Google servers.
Personal GitHub repositories which are not backed up by W3C.
Websites whose contents are not backed up on W3C-maintained servers or whose domain name is not controlled by W3C's systeam or transferrable to it should the current maintainer go out of business or get run over by a bus.

W3C Tooling Guidance NOTES

This is a proposal for discussion. It has not been adopted by the W3C. It is not intended to be part of the Process document itself, but a separate resource.

Introduction

In a spirit of innovation, W3C does not want to disallow experimenting with new tooling. However W3C also has some core values, including accessibility, internationalization, and persistence, that we want to support with our choice of tooling. This document gives guidance to groups as they explore new tooling options.

General Policy (all tools)

The formal requirements {will be in the policy} {are above} and are summarized here.

Any tool that is expected or required to be used by a member of the W3C community needs to adhere to W3C values, notably Web-for-all. This means that

the tool must meet basic accessibility requirements;
the tool must meet basic internationalization requirements;
must not cause members any direct costs (pay for use, etc.); and should not incur cost, tracking, or other client computation requirements unrelated to the direct use of the tool;
should not cause members any burdensome indirect costs (e.g. tracking, or other client computation requirements unrelated to the direct use of the tool);
should not have any 'click-through' policies, and if it does, that policy must be generally acceptable (determined by whom?);
should not be blocked for any significant portion of our membership (e.g. because it sometimes hosts adult content or pirated content, because significant national governments block it, because employers commonly forbid its use, etc.); in general the world-wide-web should be considered as world-wide, and in specific the W3C web site (w3.org and its subdomains) can be presumed to be accessible to all.

Tools used to develop W3C Deliverables (Recommendations, Notes, etc.)

General Development

W3C deliverables include Working Group drafts of documents that are intended to become Recommendations or Notes. This also includes working drafts of Community Group Reports, when that CG is associated with formal work of the W3C, such as being an incubator group for work that it is hoped/intended will transition into a WG, and these practices are recommended for all CGs.

In addition to the General Policy:

documents in development must be hosted at the W3C and backed up, or externally hosted but backed up by the W3C; if the repository goes away or the vendor becomes unacceptable, the W3C must have a backup;
tools used to host developing documents must retain history; it must be possible to examine the sequence of edits that resulted in the current state (commits, pull requests, or whatever the tool calls them);
it should be possible to request and receive notifications on change of the document, e.g. for an individual to get notifications on change, so people and other groups can 'watch progress'. (this is a weaker version of the review requirement below)
the hosting tool must be setup in such a way that review (cross-functional, wide, AC, review for example) can be managed using automatic notifications, e.g. sending notifications and periodic summaries to interested populations; (the i18n group has this at least partly set up for Github, and the systeam can send digest summaries of Github activity)
it must be possible for any member of the community (including the general public) to raise issues/bugs against deliverables and to participate in follow-up conversations with members of the group; reported issues and follow-up comments must be archived and backed up by W3C for reference by current and future members of the community

Tools used to help write documents

(e.g. reSpec, Bikeshed):

something here?

Deliverables of the W3C

Deliverables must be addressed by W3C URL (which under some circumstances can be served via a re-direct or proxy). Any other publication produced by W3C and intended for use by the general community must be addressed by a URL that W3C does or can control, so that its URL can remain serviceable for as long as W3C exists, even if that is longer than the life of its original hosting service.

Tools used to manage W3C Groups (Working, Business, Interest, etc.)

The tools used by a group, in addition to adhering to the General Policy:

should be documented on a page that is clearly the "main group page", so a newcomer or drop-in can find their way in;
must be backed up by the W3C when the tool hosts traces of discussion or formal decision;
should be amenable to analysis and reporting (e.g. reports on emails sent per month);
must maintain history indefinitely, so that people can look back and understand preceding decisions, discussions, etc.

We have a historical "hole" in calendaring, which badly needs filling. Meetings and deadlines should be announced and managed in UTC, in calendar files or systems that enable machine/automatic conversion to local times.

Tools used in general W3C operations

TBD. This would cover items like translationing and captioning, internal and W3C-hosted general tools like WBS, and so on.

Notes for discussion / incorporation in policy

Avoid absolutes: tooling choices, like others, involve tradeoffs. Groups aware of the general guidance should be able to seek/make exceptions and report on their reasoning and experience. Too many MUSTS may constrain us from using tools that would serve our overall purposes better. --@wseltzer