Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Registries #335

Merged
merged 1 commit into from
Mar 10, 2021
Merged

Registries #335

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
280 changes: 274 additions & 6 deletions index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2259,7 +2259,9 @@ W3C Technical Reports</h3>
on its <a href="https://www.w3.org/TR/">Technical Reports page https://www.w3.org/TR</a> [[TR]].

This chapter describes the formal requirements
for [=publishing=] and maintaining a [=W3C Recommendation=] or [=Note=].
for [=publishing=] and maintaining a [=W3C Recommendation=],
[=Note=],
or [=Registry Report=].

<dl>
<dt>Recommendations
Expand All @@ -2283,9 +2285,20 @@ W3C Technical Reports</h3>
and best practices for its use.
See [[#Note]] for details.

<!--
<dt>Registries
-->
<dd>
[=Working Groups=] can also publish registries
in order to document collections of values or other data
that have no normative implementation requirements.
Registries are generally companion to [=Recommendation Track=] documents
which contain the related normative requirements,
and are typically published in a separate [=registry report=],
although they can also be directly embedded in [=Recommendation Track=] documents.
The registry track requires [=wide review=] and [=consensus=]
on what the registry will contain and how it will be managed.
Once set up, changes to registry entries are lightweight
and can even be done without a [=Working Group=].
See [[#registries]] for details.
</dl>


Expand Down Expand Up @@ -2425,9 +2438,11 @@ Wide Review</h5>
<h4 id="correction-classes">
Classes of Changes</h4>

This document distinguishes the following 4 classes of changes to a specification.
The first two classes of change are considered <dfn id="editorial-change">editorial changes</dfn>,
the latter two <dfn id="substantive-change">substantive changes</dfn>.

This document distinguishes the following 5 classes of changes to a specification.
The first two classes of change are considered <dfn lt="editorial change">editorial changes</dfn>,
the next two <dfn lt="substantive change">substantive changes</dfn>,
and the last one <dfn lt="registry change">registry changes</dfn>.

<dl>
<dt>
Expand Down Expand Up @@ -2482,6 +2497,11 @@ Classes of Changes</h4>
4. New features
<dd>
Changes that add a new functionality, element, etc.

<dt>
5. Changes to the contents of a [=registry table=]
<dd>
Changes that add, remove, or alter [=registry entries=] in a [=registry table=].
</dl>

<h4 id="errata">
Expand Down Expand Up @@ -3932,6 +3952,254 @@ Revising W3C Statements</h4>
The decision to incorporate [=proposed amendments=] into [=W3C Statement=] is a [=W3C Decision=].
[=Advisory Committee representatives=] may initiate an [=Advisory Committee Appeal=] of the decision.

<h3 id="registries">
The Registry Track</h3>

A <dfn>registry</dfn> documents a data set
consisting of one or more associated <dfn lt="registry table">registry tables</dfn>,
each table representing an updatable collection
of logically independent, consistently-structured <dfn lt="registry entry">registry entries</dfn>.
A registry has three associated components:
<ul>
<li>the [=registry definition=], defining how the [=registry tables=] are structured and maintained
<li>one or more [=registry tables=], holding the data set represented by the [=registry=] (the <dfn>registry data</dfn>)
<li>one or more referencing specifications, which make use of the [=registry=]
</ul>

The purposes of maintaining a [=registry=] can include:

<dl>
<dt>non-collision
<dd>
Avoiding the problem
of two entities using the same value with different semantics.

<dt>non-duplication
<dd>
Avoiding the problem
of having two or more different values in use with the same semantics.

<dt>information
<dd>
Providing a central index
where anyone can find out
what a value means
and what its formal definition is
(and where it is).

<dt>submission
<dd>
Ease of adding new terms,
including by stakeholders external to the [=custodian=] organization.

<dt>consensus
<dd>
Promoting a clear consensus of the community on the terms.
</dl>

This section of the W3C Process provides a specialized process
facilitating the publication and maintenance of such [=registry tables=],
particularly those required by or closely related to [=W3C Recommendations=].

Note: Not every table in a specification is a potential registry.
If the intent or effect is that the table enumerates
all the possibilities the authors of the specification expect or envisage,
then the table by itself is enough.
Similarly, if the table is managed by the Working Group
and only updated as part of specification update,
then the complexities of registry management are not needed.

<h4 id=reg-def>
Registry Definitions</h4>

A <dfn>registry definition</dfn>
defines what each [=registry table=] is and how it is maintained.
It <em class=rfc2119>must</em>:

<ul>
<li>
Define the scope and purpose of each [=registry table=].

<li>
Define the fields of each [=registry table=]
and their constraints
(e.g. values must be drawn from a defined set, or be unique,
or only reference publicly available resources,
etc.)

<li>
Define the policy for changes to existing entries, such as
<ul>
<li>whether entries can be deleted or deprecated
<li>whether entries can be changed after being published, and what kinds of changes are allowed
<li>whether previously-deleted unique identifiers can be re-used, or are reserved indefinitely
</ul>

<li>
Define the method and criteria by which changes are proposed, approved, and incorporated.
(For example, a [=registry=] could define
that changes to [=registry entries=] can be proposed using a particular web form or email address,
that they must be accompanied by certain background information,
or that they do or do not need to be approved by any member of a particular Working Group.)

<li>
Identify the <dfn>custodian</dfn> of the [=registry table=]:
the entity to which requests for [=registry changes=] must be sent,
and which is responsible for evaluating whether such requests
satisfy the criteria defined in the [=registry definition=].

The [=custodian=] may be the [=Working Group=], the [=Team=], or a delegated entity.
The [=custodian=] for all [=registry tables=] in a single [=registry=]
<em class=rfc2119>should</em> generally be the same entity.
</ul>

<h4 id=reg-pub>
Publishing Registries</h4>

[=Registries=] can be published either
as a stand-alone [=technical report=] on the [=Registry Track=] called a <dfn>registry report</dfn>,
or incorporated as part of a [=Recommendation=] as a <dfn>registry section</dfn>.

A [=registry report=] or [=registry section=]
is purely documentational,
is not subject to the W3C Patent Policy,
and <em class=rfc2119>must not</em> contain any requirements on implementations.

The [=registry report=] or [=registry section=] <em class=rfc2119>must</em>:
<ul>
<li>
Clearly label the [=registry report=]/[=registry section|section=],
its [=registry tables|tables=],
and its [=registry definitions=] as such,
including a link to [[#registries]] in this Process.

<li>
Include the [=registry definition=] for each of its [=registry tables=].

<li>
Include the entire contents of each [=registry table=],
either inline in the report
(e.g. formatted as a table, or list, or other appropriate representation),
or in a machine-readable file published as part of the [=technical report=],
or (preferably) both.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

or as a link to a document or documents published elsewhere.


<li>
Include, if the [=registry table=] is provided in a machine-readable file,
a definition of the format of that file.
</ul>

The [=Team=] <em class="rfc2119">must</em> make available
a means for interested parties to be notified of any updates to a [=registry table=].

Note: Since the Process does not impose requirements
on changes to the contents of a [=registry table=]
other than those imposed by the [=registry definition=],
acceptance of proposed [=registry changes=] on behalf of the [=custodian=] and
publication of an updated [=registry report=] that contains
only [=registry changes=] since the previous publication
can be automated
if satisfaction of those rules can be automatically verified.

Rules for publication and advancement on the <dfn>Registry Track</dfn>
are identical to that of the [=Recommendation Track=]
with the following exceptions:

<ul>
<li>
Since [=Registry Reports=] are not subject to the [[PATENT-POLICY]],
none of their publications correspond,
to [=First Public Working Draft=],
[=Working Draft=],
or [=Patent Review Draft=]
for the purposes of the [[PATENT-POLICY]].

<li>
For the same reason,
there is no equivalent to [=Rescinded Recommendation=]
nor to [=Rescinded Candidate Recommendation=] for [=Registries=].

<li>
The equivalent of [=Working Draft=] is called <dfn export>Draft Registry</dfn>.

<li>
The equivalent of [=Candidate Recommendation=] is called <dfn export>Candidate Registry</dfn>,
with [=Candidate Recommendation Snapshot=] and [=Candidate Recommendation Draft=] corresponding to
<dfn export>Candidate Registry Snapshot</dfn> and <dfn export>Candidate Registry Draft</dfn>.

<li>
The equivalent of [=W3C Recommendation=] is called <dfn export>W3C Registry</dfn>;
[=Obsolete Recommendation=] and [=Superseded Recommendation=] correspond to
<dfn export>Obsolete Registry</dfn> and <dfn export>Superseded Registry</dfn>.

<li>
The [=Proposed Recommendation=] phase is eliminated.
Instead,
an [=Advisory Committee Review=] is started
upon publication of each [=Candidate Registry Snapshot=].

<li>
Changes that add new features (i.e. [[#correction-classes|class 4 changes]]) are allowed
in all [=W3C Registries=],
without needing the to explicitly indicate that this is allowed.
</ul>

<h4 id=reg-table-update>
Updating Registry Tables</h4>

Changes to the contents of a [=registry table=] that are in accordance with the [=registry definition=],
(i.e. [[#correction-classes|Class 5 changes]])
can be made by re-publishing the [=technical report=] that contains the affected table,
without needing to satisfy any other requirements for the publication
(not even Working Group consensus, unless this is required by the [=registry definition=]).
Such [=registry changes=] do not trigger new [=Advisory Committee Reviews=],
nor Exclusion Opportunities,
and do not require approval via an [=update request=],
even for [=technical reports=] at maturities where this would normally be expected.
Such publications can be made
even in the absence of a [=Working Group=] chartered to maintain the registry
when the [=custodian=] is another entity.

Note: The custodian is only empowered to make [=registry changes=].
If the Working Group establishing the registry wishes
to empower the custodian to add commentary on individual entries,
this needs to be part of the registry table’s defintion.
If other changes are desired,
they must be requested of the responsible Working Group--
or in the absence of a Working Group, of the Team.

Changes to the [=registry tables=]
made in accordance with [=candidate amendment|candidate=] or [=proposed amendments=] to the [=registry definition=]
which would not be allowed by the unamended [=registry definition=]
<em class=rfc2119>must</em> be identified as such.

<h4 id=reg-ref-specifications>
Specifications that Reference Registries</h4>

All rules and statements about implementations of [=registries=]
<em rfc=2119>must</em> be contained in the specifications or other documents that reference the registry,
and are therefore subject to the processes
(including approval and intellectual property provisions)
applicable to those referencing specifications.

It <em class=rfc2119>must not</em> be possible that a change to the [=registry entries=]
affect the conformance of implementations to the Referencing document;
if there are entries that must be implemented,
or any other such restrictions,
they <em rfc=2119>must</em> be documented in the document without reference to the registry.

<div class=example>
For example,
“All implementations must implement the <code>Basic-Method</code> as defined in the registry”
is not acceptable;
a change to the definition of the <code>Basic-Method</code> in the registry would then affect conformance.
Instead, the requirement must be complete in the specification,
directly or by reference to another specification.
For example
“All implementations must recognize the name <code>Basic-Method</code>,
and implement it as defined by section yy of IETF RFC xxxx”.
(The Registry should nonetheless contain </code>Basic-Method</code> as an entry.)
</div>

<h3 id="further-reading">
Further reading</h3>

Expand Down