-
Notifications
You must be signed in to change notification settings - Fork 5
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.
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
Draft boilerplate text #243
Merged
Merged
Changes from all commits
Commits
Show all changes
9 commits
Select commit
Hold shift + click to select a range
6845473
WIP first draft boilerplate text
nigelmegitt 7b611a4
Create boilerplate/registry/.pr-preview.json
nigelmegitt b47e458
More WIP
nigelmegitt adbd271
Clarify key reuse and requirements on status of new entries
nigelmegitt d093d14
Fix up links to defined terms, add introduction text.
nigelmegitt 4978e7f
Insert an example registry table.
nigelmegitt 05ef9ab
Address review comment
nigelmegitt ed31515
Use consistent style for refs, and fix W3C Team ref
nigelmegitt 0465129
Clarify that one or more fields are used as the key
nigelmegitt File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,4 @@ | ||
| { | ||
| "src_file": "index.html", | ||
| "type": "respec" | ||
| } | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,4 @@ | ||
| { | ||
| "src_file": "index.html", | ||
| "type": "respec" | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| See https://github.com/w3c/ttwg/discussions/241 for | ||
| the motivation and discussion of this boilerplate registry document | ||
| for TTWG use. | ||
|
|
||
| The boilerplate is a Respec document, | ||
| though the text content can be reused | ||
| within any other document. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,297 @@ | ||
| <!DOCTYPE html> | ||
| <html> | ||
| <head> | ||
| <meta charset="utf-8" /> | ||
| <title>TTWG Registry Boilerplate</title> | ||
| <script | ||
| src="https://www.w3.org/Tools/respec/respec-w3c" | ||
| class="remove" | ||
| defer | ||
| ></script> | ||
| <script class="remove"> | ||
| // All config options at https://respec.org/docs/ | ||
| var respecConfig = { | ||
| specStatus: "RY", | ||
| editors: [{ name: "Nigel Megitt", w3cid: "64750", mailto: "nigel.megitt@bbc.co.uk", url: "", company: "British Broadcasting Corporation", companyURL: "https://www.bbc.co.uk" }], | ||
| github: "w3c/ttwg", | ||
| shortName: "ttwgreg", | ||
| edDraftURI: "https://w3c.github.io/ttwg/boilerplate/registry", | ||
| group: "wg/timed-text", | ||
| wgPublicList: "public-tt", | ||
| xref: ["w3c-process"], | ||
| localBiblio: { | ||
| ttwg: { | ||
| title: "Timed Text Working Group", | ||
| href: "https://www.w3.org/AudioVideo/TT/" | ||
| } | ||
| } | ||
| }; | ||
| </script> | ||
| </head> | ||
| <body> | ||
| <section id="abstract"> | ||
| <p>This is a boilerplate Registry Definition as required by [[w3c-process]] for <a>w3c registries</a>.</p> | ||
| <p>The intent is that this boilerplate can form the basis of <a>w3c registries</a> for | ||
| the W3C <dfn data-abbr="TTWG"><a href="https://www.w3.org/AudioVideo/TT/">Timed Text Working Group</a></dfn>.</p> | ||
| <p>See discussion <a href="https://github.com/w3c/ttwg/discussions/241">w3c/ttwg#241</a> for | ||
| details of the assumptions made to generate this document.</p> | ||
| </section> | ||
| <section id="sotd"> | ||
| <p>This document is intended to be the basis of other <a>w3c registries</a> | ||
| published by TTWG and is not intended to be published as a <a>w3c registry</a> itself. | ||
| The following SOTD text is auto-generated by the Respec tool to reflect | ||
| what an actual <a>registry definition</a> document would contain.</p> | ||
| </section> | ||
| <section class="informative"> | ||
| <h2>Introduction</h2> | ||
| <p>Replace the text in this section with some | ||
| informative introductory text about this Registry.</p> | ||
| <p>This document is intended to be used as the basis for <a>w3c registries</a> for | ||
| the W3C <a>TTWG</a>. | ||
| The [[w3c-process]] sets out requirements for such <a>w3c registries</a>, | ||
| and defines core concepts like | ||
| <dfn data-cite="w3c-process#registry-definition">registry definition</dfn> | ||
| and <dfn data-cite="w3c-process#registry-table">registry table</dfn>.</p> | ||
| <p><a>Registry definitions</a> need to fulfil certain criteria, | ||
| including specifying custodianship, the change process, | ||
| and defining the <a>registry table</a> itself.</p> | ||
| <p>The text in the <a href="#registry-definition"></a> section can be | ||
| used to meet those criteria and allow more rapid creation of | ||
| registries without having to create new text each time.</p> | ||
| <p>This document also includes appendix <a href="#application-checklist"></a> | ||
| to facilitate adoption.</p> | ||
| </section> | ||
| <section id="registry-definition"> | ||
| <h2>Registry Definition</h2> | ||
| <p>This section specifies the <a>registry definition</a>, consisting of | ||
| the custodianship, change process and | ||
| the core requirements of a <a>registry table</a>. | ||
| </p> | ||
| <section id="custodianship"> | ||
| <h3>Custodianship</h3> | ||
| <p>The <dfn data-cite="w3c-process#custodian">custodian</dfn> of this <a>w3c registry</a> is the <a>TTWG</a>. | ||
| If the <a>TTWG</a> is unable to fulfil the role of <a>custodian</a>, | ||
| for example if it has been <a data-cite="w3c-process#GeneralTermination">closed</a>, | ||
| the <a>custodian</a> in lieu is the <a>W3C Team</a>. | ||
| </p> | ||
| <p class="issue" data-number="244"></p> | ||
| </section> | ||
| <section id="change-process"> | ||
| <h3>Change Process</h3> | ||
| <section id="requesting-a-change"> | ||
| <h4>Requesting a change</h4> | ||
| <p>Changes to this <a>W3C Registry</a> MUST be requested (the <dfn>change request</dfn>) | ||
| using any one of the following options:</p> | ||
| <ul> | ||
| <li>Open an issue on the <a>registry table</a>'s version control system;</li> | ||
| <li>Send an email to the <a>TTWG</a>'s public email reflector | ||
| <a href="mailto:public-tt@w3.org">public-tt@w3.org</a></li> | ||
| </ul> | ||
| <p>The <a>change request</a> MUST include enough information for the <a>custodian</a> | ||
| to be able to identify all of:</p> | ||
| <ul> | ||
| <li>The <a>registry table</a>;</li> | ||
| <li>The <a>registry entries</a> being proposed for addition;</li> | ||
| <li>The <a>provisional</a> <a>registry entries</a> for which changes are being proposed;</li> | ||
| <li>The <a>registry entries</a> being proposed for a <a>status</a> change;</li> | ||
| <li>Details of the requested changes for each <a>registry entry</a>;</li> | ||
| <li>The motivation for making the requested changes;</li> | ||
| <li>Any other supporting information, for example real world usage statistics;</li> | ||
| </ul> | ||
| <p>The proposer of the change MAY open a pull request (or equivalent) on | ||
himorin marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| the <a>registry table</a>'s version control system, with that pull request | ||
| containing the proposed changes. If a pull request is opened then | ||
| a corresponding issue MUST also be opened and | ||
| the pull request MUST be linked to that issue.</p> | ||
| <aside class="note">A pull request representing the proposals made in the <a>change request</a> | ||
himorin marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| is required before <a>TTWG</a> review can proceed.</aside> | ||
| </section> | ||
| <section id="change-request-assessment"> | ||
| <h4>Change request assessment process</h4> | ||
| <p>The process for assessing a <a>change request</a> depends on the <a>custodian</a>.</p> | ||
| <section id="ttwg-change-request-assessment"> | ||
| <h5>Custodian is TTWG</h5> | ||
| <p>If the <a>custodian</a> is the <a>TTWG</a>:</p> | ||
| <ul> | ||
| <li>If the change proposer did not open a pull request | ||
| on the <a>registry table</a>'s version control system, | ||
| then assessment is paused until a TTWG member | ||
| has opened such a pull request, | ||
| which MUST represent the requested changes | ||
| and MUST be linked to a related issue.</li> | ||
| <li>The TTWG follows its Decision Policy to review | ||
| the proposal in the pull request.</li> | ||
| <li>At the end of the Decision Review Period | ||
| if a TTWG Chair declares that there is consensus to approve, | ||
| the <a>change request</a> is approved.</li> | ||
| <li>In the absence of consensus to approve the expectation is | ||
| that a discussion will happen, to include the | ||
| change requester. | ||
| The result of this discussion can be any one of: | ||
| <ol> | ||
| <li>the <a>change request</a> is abandoned;</li> | ||
| <li>the <a>change request</a> is modified for another review;</li> | ||
| <li>if the discussion resolves the objections, | ||
| and a TTWG Chair declares consensus to approve, | ||
| the <a>change request</a> can be approved.</li> | ||
| </ol> | ||
| </li> | ||
| </ul> | ||
| <p>An approved <a>change request</a> is enacted by merging its | ||
| related pull request into the <a>registry table</a>'s version control system | ||
| and publishing the updated version of the <a>registry table</a>.</p> | ||
| </section> | ||
| <section id="team-change-request-assessment"> | ||
| <h5>Custodian is the W3C Team</h5> | ||
| <p>If the <a>custodian</a> is the <a>W3C Team</a>, | ||
| the Team MUST seek <a>wide review</a> of the <a>change request</a> and | ||
| offer a review period of at least 4 weeks, | ||
| before assessing from the responses received | ||
| if there is consensus amongst the respondents.</p> | ||
| <p>The Team MAY require a pull request on the <a>registry table</a>'s | ||
| version control system to be | ||
| opened as the basis of the review. | ||
| </p> | ||
| <p>If there is such consensus, | ||
| the Team MUST make the proposed changes.</p> | ||
| </section> | ||
| </section> | ||
| </section> | ||
| <h3>Registry Table(s)</h3> | ||
| <p>This section defines constraints on <a>registry tables</a>. | ||
| Each <a>registry table</a> consists of a set of | ||
| <dfn data-cite="w3c-process#registry-entry" data-lt="registry entry|registry entries">registry entries</dfn>.</p> | ||
| <p>The <a>registry table</a> MUST provide a link to the version control system against | ||
| which any issues and pull requests can be opened.</p> | ||
| <section id="registry-entries"> | ||
| <h4>Registry Entries</h4> | ||
| <p>Each <a>registry entry</a> has a <a>status</a>, a unique <dfn>key</dfn>, and | ||
| if appropriate, other <dfn>fields</dfn>, for example any notes, | ||
| a description, or a reference to some other | ||
| defining entity. | ||
| </p> | ||
| <p>The <a>registry table</a> definition MUST define | ||
| the <a>fields</a> and the <a>key</a> to be used | ||
| in each <a>registry entry</a>.</p> | ||
| <aside class="note">It is possible to use any <a>field</a> | ||
| or combination of <a>fields</a> as the <a>key</a>. | ||
| For example a <a>field</a> called "4 Character Code" | ||
| might be used as the <a>key</a>. | ||
| Another example is two fields called "Short name" and | ||
| "Revision number" which, in combination, | ||
| might be used as the <a>key</a>. | ||
| </aside> | ||
|
|
||
| <section id="registry-entry-status"> | ||
| <h5>Status</h5> | ||
| <p>The <a>registry entry</a> <dfn>status</dfn> field reflects the maturity of that entry. | ||
| Permitted values are:</p> | ||
| <pre> | ||
| Provisional | ||
| Final | ||
| Deprecated | ||
| </pre> | ||
| <p>No other values are permitted.</p> | ||
| <section id="provisional-entry"> | ||
| <h6>Provisional</h6> | ||
| <p><a>Registry entries</a> with a <a>status</a> of <dfn><code>Provisional</code></dfn> MAY be changed or deleted. | ||
| Their <a>status</a> may be changed to <a><code>Final</code></a> or <a><code>Deprecated</code></a>.</p> | ||
| <p><a>Registry entry</a> <a>keys</a> in <a><code>Provisional</code></a> entries | ||
| that were later deleted MAY be reused.</p> | ||
himorin marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| <p>Newly created <a>registry entries</a> SHOULD have <a>status</a> <a><code>Provisional</code></a>.</p> | ||
| </section> | ||
| <section id="final-entry"> | ||
| <h6>Final</h6> | ||
| <p><a>Registry entries</a> with a <a>status</a> of <dfn><code>Final</code></dfn> MUST NOT be deleted or changed. | ||
| Their <a>status</a> MAY be changed to <a><code>Deprecated</code></a>.</p> | ||
| <p><a>Registry entry</a> <a>keys</a> in <a><code>Final</code></a> entries MUST NOT be reused.</p> | ||
| <p>Newly created <a>registry entries</a> MAY have <a>status</a> <a><code>Final</code></a>.</p> | ||
| </section> | ||
| <section id="deprecated-entry"> | ||
| <h6>Deprecated</h6> | ||
| <p><a>Registry entries</a> with a <a>status</a> of <dfn><code>Deprecated</code></dfn> MUST NOT be deleted or changed. | ||
| Their <a>status</a> MAY be changed to <a><code>Final</code></a> | ||
| unless that would result in a duplicate <a>key</a> within the set of entries whose | ||
| <a>status</a> is either <a><code>Provisional</code></a> or <a><code>Final</code></a>.</p> | ||
| <p><a>Registry entry</a> <a>keys</a> in <a><code>Deprecated</code></a> entries | ||
| that were previously <code>Provisional</code> and never <a><code>Final</code></a> | ||
| MAY be reused.</p> | ||
| <p><a>Registry entry</a> <a>keys</a> in <a><code>Deprecated</code></a> entries | ||
| that were previously <a><code>Final</code></a> MUST NOT be reused.</p> | ||
| <p>Newly created <a>registry entries</a> MUST NOT have <a>status</a> <a><code>Deprecated</code></a>.</p> | ||
| </section> | ||
| </section> | ||
| </section> | ||
| </section> | ||
| <section id="registry-table"> | ||
| <h2>Registry Table(s)</h2> | ||
| <p>This section contains the <a>registry table</a>, i.e. the set of <a>registry entries</a>.</p> | ||
| <table class="simple"> | ||
| <thead> | ||
| <th>Key</th> | ||
| <th>Status</th> | ||
| <th>Other fields</th> | ||
| <th>Notes</th> | ||
| </thead> | ||
| <tbody> | ||
| <tr> | ||
| <td>abc1</td> | ||
| <td>Provisional</td> | ||
| <td></td> | ||
| <td>This key reuses one that was deprecated without being Final</td> | ||
| </tr> | ||
| <tr> | ||
| <td>abc2</td> | ||
| <td>Final</td> | ||
| <td></td> | ||
| <td>This entry cannot be changed, but it can be Deprecated.</td> | ||
| </tr> | ||
| <tr> | ||
| <td>abc1</td> | ||
| <td>Deprecated</td> | ||
| <td></td> | ||
| <td>This was never made Final, and now it cannot be, because its key has been reused.</td> | ||
| </tr> | ||
| </tbody> | ||
| </table> | ||
| </section> | ||
| <section id="conformance"> | ||
| <p> | ||
| No conformance requirements are permitted in <a>registry tables</a>. | ||
| If there are conformance requirements associated with | ||
| <a>registry entries</a>, then they must be defined in the | ||
| referencing specification. | ||
| </p> | ||
| <section id="referencing-specifications"> | ||
| <h3>Referencing Specifications</h3> | ||
| <p>Although the formal definition of a Registry includes | ||
| the referencing specifications, | ||
| there is no need to list those referencing specifications | ||
| in the Registry itself; doing so is optional. | ||
| Listing referencing specifications carries an | ||
| additional maintenance overhead. | ||
| </p> | ||
| </section> | ||
| </section> | ||
|
|
||
| <section id="index" class="appendix"> | ||
| <!-- All the terms will magically appear here --> | ||
| </section> | ||
|
|
||
| <section class="appendix" id="application-checklist"> | ||
| <h2>Checklist for applying this boilerplate to a real Registry</h2> | ||
| <p>When adopting this boilerplate for use in a Registry, | ||
| the following checklist may be helpful:</p> | ||
| <ul> | ||
| <li>Make a copy of this boilerplate and work on it in the appropriate repository;</li> | ||
| <li>Write introductory text explaining the Registry, it's purpose and expected usage;</li> | ||
| <li>Check that the custodianship rules are correct;</li> | ||
| <li>Check that the change process is correct;</li> | ||
| <li>Define the registry entry <a>fields</a>;</li> | ||
| <li>Define which of the <a>fields</a> is/are used as the <a>key</a>;</li> | ||
| <li>Create a table and populate it with any known values;</li> | ||
| <li>Update any referencing specifications to link to it.</li> | ||
| </ul> | ||
| </section> | ||
| </body> | ||
| </html> | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This file should be named as
boilerplate/registry/.pr-preview.jsoninstead of placed at the top directory?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I didn't know that could work. There's an
index.htmlin the top directory too, which is for the TTWG homepage. I've added.pr-preview.jsonto the location you suggested as well. But I think PR Preview only does one preview per repo, as far as I know. tobie/pr-preview#18 is open to support multiple specs per repo, but as you can see from the response to my comment, it's awaiting resource.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ah, I thought this
boilerplate/registrydirectory was for ready-to-copy respec template to create new repository (e.g. making new repository like w3c/tt-profile-registry). If so, this file should be at the same directory as this template, but not at the top of this repository. OR, If this PR is really to put at the top of this repository with pointingindex.html, I propose to usehtmlfor type, instead ofrespec.As pointed, pr-preview does handle only one file in each repository, yes.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That's a good point, having the
.pr-preview.jsonfile there does no harm, I think, and means there is something ready to copy. I think it's fine to leave it there and keep the type as respec, while understanding that PR Preview won't actually work with it in the current location.