generated from w3c-ccg/markdown-to-spec
-
Notifications
You must be signed in to change notification settings - Fork 1
/
index.bs
338 lines (249 loc) · 20.6 KB
/
index.bs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
<pre class='metadata'>
Title: W3C CCG Work Item Process
Shortname: CCG-WI-PROCESS
Level: 1
Status: w3c/CG-DRAFT
Group: w3c-ccg
URL: https://w3c-ccg.github.io/workitem-process/
Editor: Kim Hamilton Duffy, MIT Open Learning, kimhd@mit.edu, https://www.okimsrazor.com/
Editor: Heather Vescent, The Purple Tornado Inc https://www.thepurpletornado.com, heathervescent@gmail.com, https://www.heathervescent.com
Editor: Wayne Chang, Spruce Systems Inc. https://spruceid.com, wyc@fastmail.fm, https://wycd.net
!Authors: Joe Andrieu, Legendary Requirements, http://legreq.com/
!Authors: Christopher Allen, Blockchain Commons, http://www.lifewithalacrity.com/
Abstract: Documentation for the W3C CCG Work Item process
</pre>
<pre class="biblio">
{
"W3C-CG-GUIDELNES": {
"href": "https://www.w3.org/community/about/",
"title": "W3C community process guidelines",
"publisher": "W3C"
},
"CCG-MISSION": {
"href": "https://www.w3.org/community/credentials/",
"title": "W3C CCG Mission",
"status": "Adopted",
"publisher": "W3C CCG"
},
"W3C-CCG-PAGE": {
"href": "https://www.w3.org/community/credentials/",
"title": "W3C Credentials Community Page",
"publisher": "W3C CCG"
},
"W3C-CLA": {
"href": "https://www.w3.org/community/about/agreements/cla/",
"title": "W3C Community Contributor License Agreement (CLA)",
"publisher": "W3C"
},
"CG-PROCESS": {
"href": "https://www.w3.org/community/about/faq/#how-do-we-publish-a-specification",
"title": "Community Group Process FAQ",
"publisher": "W3C"
},
"CG-REPORT": {
"href": "https://www.w3.org/community/about/faq/#how-do-we-publish-a-report",
"title": "Community Group Report FAQ",
"publisher": "W3C"
},
"CG-REQUIREMENTS": {
"href": "https://www.w3.org/community/reports/reqs/",
"title": "Community Group Requirements",
"publisher": "W3C"
},
"CG-FINAL-REPORT": {
"href": "https://www.w3.org/community/reports",
"title": "Community Group Final Reports",
"publisher": "W3C"
},
"CCG-GITHUB": {
"href": "https://github.com/w3c-ccg/",
"title": "CCG Github Organization",
"publisher": "W3C-CCG"
},
"CCG-GITHUB-ISSUES": {
"href": "https://github.com/w3c-ccg/community/issues",
"title": "CCG Github Issues",
"publisher": "W3C-CCG"
},
"CCG-WORK-ITEMS": {
"href": "https://github.com/w3c-ccg/community/blob/master/work_items.md",
"title": "CCG Work Items",
"publisher": "W3C-CCG"
},
"CCG-CREATE-REPO": {
"href": "https://w3c-ccg.github.io/create_repo.html",
"title": "CCG Create Repo",
"publisher": "W3C-CCG"
},
"SEMVER": {
"href": "https://semver.org/",
"title": "Semantic Versioning"
},
"FORMER-CCG-PROCESS": {
"href": "https://www.google.com/url?q=https://www.w3.org/community/credentials/charter/&sa=D&ust=1519088657480000&usg=AFQjCNEjYaISD-6RIE-awU-dHiofJrsaVg",
"title": "Former CCG Process"
},
"W3C-CANDIDATE-REC": {
"href": "https://www.w3.org/2005/10/Process-20051014/tr.html#q74",
"title": "W3C Candidate Recommendation"
},
"W3C-WG-NOTE": {
"href": "https://www.w3.org/2005/10/Process-20051014/tr.html#q75",
"title": "W3C Working Group Note"
},
"W3C-WG": {
"href": "https://www.w3.org/groups/wg/",
"title": "W3C Working Groups"
},
"CCG-PROPOSE-WORK-ITEM": {
"href": "https://w3c-ccg.github.io/propose_work_item.html",
"title": "Propose a CCG Work Item",
"publisher": "W3C-CCG"
}
}
</pre>
Introduction {#intro}
=====================
To streamline and clarify how the W3C Credentials Community Group operates, this document outlines the process by which a CCG [=work item=] is created, managed, and finalized by the group.
Terminology {#terminology}
===========
<dfn>community report</dfn>: A [=category=] of CCG [=work item=] whose [=target deliverable=] is a collaborative document, with the goal of being completed and published by the CCG as a [=final report=] on [[W3C-CCG-PAGE]]. A [=community report=] must not suggest it is a standard or on the W3C standard track.
<dfn>ongoing community draft</dfn> — A [=category=] of CCG [=work item=] with a [=ccg repository=] that will be maintained by the CCG in perpetuity. It is not intended to beome a [=final report=]. Examples include registries, conformance tests, schemas, reference code, etc.
<dfn>task force</dfn> — A [=category=] of CCG [=work item=] that meets on a regular basis to address a specific topic within the scope of the CCG. It is not intended to beome a [=final report=] and may be concluded at any time by the participants. Examples include the VC-EDU task force, Secure Data Storage task force and DID Resolution task force. From time to time, task forces will provide updates to the main CCG community.
<dfn>community specification</dfn>: A [=type=] of [=community report=], with intended transition to becoming a standard track working group [[W3C-CANDIDATE-REC]]
<dfn>community note</dfn>: A type of [=community report=], with intended transition to becoming a [[W3C-WG-NOTE]]
<dfn>community commentary</dfn>: A type of [=community report=] not intended to transition to a [[W3C-WG]].
<dfn>rough draft</dfn>: A [=stage=] of a [=community report=] [=work item=] that is not yet available in a [=ccg repository=], but is being iterated on via whatever medium or format the editors favor, e.g., Google Docs, Github, etc
<dfn>unreleased draft</dfn>: A [=stage=] of a [=community report=] [=work item=] that exists as a [=ccg repository=] but which is not yet a [=released draft=]
<dfn>released draft</dfn>: A [=stage=] of a [=community report=] [=work item=] that is tagged with a git release number but not published to W3C.
<dfn>published draft</dfn>: A [=stage=] of [=community report=] [=work item=] in which CCG chairs have approved a [=released draft=] and published it on the [[W3C-CCG-PAGE]]
<dfn>final report</dfn>: A [=stage=] of [=community report=] [=work item=] in which a [=published draft=] has been approved by the CCG community and the W3C staff, and is considered accepted as a [[CG-FINAL-REPORT]].
<dfn>conformance test suite</dfn>: A [=type=] of [=ongoing community draft=], with the goal as being a companion to a [=community specification=] for testing of conformance.
<dfn>registry</dfn>: A [=type=] of [=ongoing community draft=], with the goal of providing an informative, long-lived list (such as credential status methods, DID methods, Linked Data Key Types)
<dfn>schema</dfn>: A [=type=] of [=ongoing community draft=], with the goal of providing reference schemas, such as JSON-LD contexts or JSON schemas.
<dfn>experimental implementation</dfn>: A [=type=] of [=ongoing community draft=], with the goal of providing an example implementation of a [=community specification=].
<dfn>work item</dfn>: An effort that is adopted by the CCG for further development and refinement. The process for CCG work items is described in this document.
<dfn>release tag</dfn>: A git concept for "freezing" a git artifact.
<dfn>ccg repository</dfn> , for iteration by CCG members through discussion, issues, and pull requests,
<dfn>proposal</dfn>: The initial [=stage=] of a CCG [=work item=] in which the CCG member announces their intention.
<dfn>adoption</dfn>: The [=stage=] after [=proposal=] in which the CCG community discusses the proposed [=work item=]
<dfn>draft</dfn>: The [=stage=] after a CCG [=work item=] has been accepted
<dfn>final</dfn>: The final success [=stage=] of CCG [=work item=]. This only applies to [=community report=] [=work items=], and not [=ongoing community drafts=].
<dfn>archived</dfn>: A [=stage=] of CCG [=work item=] which has been retired by the Chairs due to inactivity
<dfn>stage</dfn>: Refers to a phase of a CCG [=work item=] within the overall lifecycle
<dfn>category</dfn>: A course classification of CCG [=work items=]
<dfn>type</dfn>: A finer classification of CCG [=work items=]
<dfn>target deliverable</dfn>: The desired output or outcome of a CCG [=work item=], which corresponds to CCG's [=work item=] classifications
## Work Item Requirements
### W3C Requirements
As per [[W3C-CG-GUIDELNES]], W3C Community Groups (CGs) are established for communities of stakeholders to socialize their ideas for possible future standardization. CGs can publish documents with relatively minimal process and requirements other than that contributors agree to the [[W3C-CLA]].
The CCG manages a large number of work items, and in the course of its work, has developed conventions and tools to help streamline the process for its members, as well as guidelines and requirements to enable the chairs to manage the group more effectively. This document is designed to conform to W3C's [[CG-PROCESS]] and [[CG-REQUIREMENTS]], which are the ultimate requirements for a W3C community group.
Group members may propose a different process for their work item, which the chairs may choose to accept (on a case-by-case basis) as long as the W3C's [[CG-PROCESS]] and [[CG-REQUIREMENTS]] are met.
NOTE: Long term these may be replaced by new W3C processes, but currently as Working Groups currently terminate, until a new process for these is created by the W3C we maintain them as community groups are perpetual.
### Additional CCG Requirements
The CCG has additional requirements in order to adopt a [=work item=]:
- at least one group member willing to commit to being the first editor
- another group member (from a different company) willing to be a co-editor
- a suggested timeline
- address the [=work item=] questions below in their [=proposal=]
- a link to the <a href="https://www.w3.org/Consortium/cepc/">W3C Code of Ethics and Professional Conduct</a>
- the expected [=work item=] [=type=]
### Work Item Scope
In general, any work that advances the [[CCG-MISSION]] is welcome for consideration as a [=work item=].
### Work Item Questions
Each proposed [=work item=] must answer the following questions in their [=proposal=]. These questions are based on the Heilmeir Catechism. The intention is to improve clarity and understanding of the proposed [=work item=].
- Explain what you are trying to do using no jargon or acronyms.
- How is it done today, and what are the limits of the current practice?
- What is new in your approach and why do you think it will be successful?
- How are you involving participants from multiple skill sets and global locations in this work item? (Skill sets: technical, design, product, marketing, anthropological, and UX. Global locations: the Americas, APAC, Europe, Middle East.)
- What actions are you taking to make this work item accessible to a non-technical audience?
### Work Item Best Practices
While not a requirement, the following best practices are recommended
- peer leadership. Inspired from peer programming, peer leadership is teaming less experience work item owners with experienced work item owners for hands on experience. This enables knowledge transfer and empowers a larger number of future work item owners.
## Work Item / Target Deliverable Classification
### Categories
CCG classifies its [=work item=]s by the [=target deliverable=]. The first relevant classification is a [=target deliverable=] [=category=]; the CCG distinguishes between three:
- [=community report=]
- [=ongoing community draft=]
- [=task force=]
The [=ongoing community draft=] category is not common in the W3C, but has emerged as a useful concept in the CCG to cover ongoing [=work item=]s that are useful to the community, while not being intended to turn into a [=final report=]
The [=task force=] category is not common in the W3C, but has emerged as a useful activity in the CCG to discuss topics of importance to the community. Task forces must have
- at least one leader
- completed requirements for a [=work item=]
- a charter which defines the scope, deliverables, work principles, relationships to external groups, participation and communication. The charter should be readily accessible outside of GitHub and a copy should be sent to the mailing list for archival purposes.
For a task force to remain active, it must
- provide a status update report within a timely manner of the chairs' request (meeting minutes will typically suffice)
If a response is not rendered within two weeks of the chairs' request, then the chairs may deem the task force to be inactive.
### Types
These [=categories=] are further broken down into the following [=target deliverable=] [=types=]:
* [=community report=]: There are three kinds of [=community report=], each of which has the goal of transitioning to a [=final report=], as follows:
* [=community specification=]
* [=community note=]
* [=community commentary=]
* [=ongoing community draft=]: This is not a strict or exhaustive list, just groupings that the CCG has found useful:
* [=conformance test suite=]
* [=registry=]
* [=schema=]
* [=experimental implementation=]
Figure: Types of Work Items
<img src="images/types.png" width="800" alt="work item types" title="work item types">
## Work Item Lifecycle
A CCG [=work item=]'s lifecycle differs depending on its category:
Figure: Work Item Process Overview
<img src="images/wi_process_overview.png" width="400" alt="work item process overview" title="work item process overview">
The lifecycle stages are:
1. [=proposal=]
2. [=adoption=]
3. [=draft=]
4. [=archived=]
5. [=final=] -- not relevant for [=ongoing community draft=]
### Proposal Stage
A more concise version of this information is made available at [[CCG-PROPOSE-WORK-ITEM]].
A CCG member initiates a [=proposal=] by creating a [[CCG-GITHUB-ISSUES]] with the “New Work Item” template. The template prompts for the following [=proposal=] elements:
1. Abstract or Draft of proposed [=work item=] (typically a link to a google doc or a markdown page in Github)
2. Editors responsible for advancing the [=work item=]. Initially, a [=proposal=] may have a single editor; however, before approval of a [=work item=] it must have more than one editor, and editors must include representation from at least two companies.
3. Work item questions
Once the [=proposal=] github issue exists, the member should post the announcement to the CCG mailing list Credentials Community Group <[public-credentials@w3.org](mailto:public-credentials@w3.org)>, linking to the Github issue.
### Adoption Stage
Once a [=proposal=] is announced, the community group will discuss it for a period of at least one week. This discussion may take place on the mailing list and the regular conference call at the Chairs discretion. During this time, proposers should seek support and consensus around their specific [=proposal=].
Once there has been suitable opportunity for conversation, the chairs will make a determination as follows: if the chairs decide the [=work item=] is appropriate, has sufficient community support, and there are no principled objections, the chairs will formally accept the [=work item=].
### Draft Stage
Once approved, the Chairs will facilitate creation of a [=ccg repository=], as described in [[CCG-CREATE-REPO]]. . The editors will facilitate CCG progress on the [=work item=] per W3C practices including transparency and public documentation of meetings discussing the [=work item=]. To manage the intellectual property of contributions, editors should track [=work item=] contributors in the drafts.
### Final Stage
A [=work item=] that succeeds in becoming a [=final report=] is closed. Details for this follow in [[#community-report-stages]]. The existing [=ccg repository=] description will be noted as being “FINAL:”.
[=ongoing community drafts=] are not eligible to enter this stage.
### Archived Stage
If the chairs determine that progress on a [=work item=] is not progressing satisfactorily, they will notify the editors that they have one month to demonstrate progress. After this notice it is at the chairs discretion to keep the [=work item=] in the CCG roadmap, change the editors for the [=work item=], or remove the [=work item=] from the CCG roadmap and formally close the [=work item=], and the existing [=ccg repository=] description will be noted as being “CLOSED:”
ISSUE: Applies here and in following sections. The convention of marking stage by the repository description prefix may not be the best way; should we use tags instead?
## Work Item Stages, by Category
This section provides more detail to [=work item=] stages, depending on the [=work item=] [=category=]
Figure: Work Item Process Detail
<img src="images/wi_process_detail.png" width="400" alt="work item process details" title="work item process details">
### Community Report Stages
#### Rough Draft Stage
* An initial [=rough draft=] should be started by the [=work item=] proposed editors as part of the process of proposing a [=community report=] [=work item=].
* Contributions to the [=rough draft=] by CCG members are moderated in a manner suitable to the medium, under the guidance of the [=work item=] editors.
* [=work item=] editors must ensure that all substantial commitments to the [=rough draft=] are made by members that have signed the CCGs Contributors Agreement.
* Editors may iterate a [=rough draft=] [=work item=] at their initial location until they are ready, but the goal should be to transition them to a [=ccg repository=] in an acceptable format (details in [[#unreleased-draft-stage]]) as soon as reasonably possible.
#### Unreleased Draft Stage
* When the editors of a [=rough draft=] [=work item=] agree that a version of a [=rough draft=] is ready for Github, and it has been formatted in ReSpec format (or appropriate format for destination such as IETF draft format), they may migrate to the [=ccg repository=] that has been created for them.
* Issues & pull requests to the [=unreleased draft=] are moderated by the [=work item=] editors, as per W3C github cultural practices, including transparency and public documentation of [=work item=] meetings.
#### Releeased Draft Stage
* When the editors of a [=work item=] believe that the collaboration has reached some milestone (say for broader commentary by other CCG members or to the broader community), at their discretion they may mark a particular version of the [=ccg repository=] with a [=release tag=]. If the [=work item=] itself contains a version number (e.g. in its specification text), then that version must be increased with the commit following the [=release tag=]; work then continues on that next version.
* Release numbering must follow [[SEMVER]]. Work items that are WG Specifications or WG Notes track (for future transitions to the standards-track W3C Working Group Process) must be numbered below 1.0.0. Alternatively, drafts destined for non-W3C standards track may use the appropriate numbering system for the intended standards organization.
* Editors should submit a PR to [[CCG-WORK-ITEMS]] to update the [=work item=] stage and version number.
* The editors may continue to update with new releases numbers as needed.
#### Published Draft Stage
* Prior to publishing, the Editors must verify that all substantive contributors to the [=released draft=] have signed the CCGs Contributors' Agreement, and request that the chairs publish the draft to the W3C.
* The chairs determine when a [=released draft=] is ready to listed as a [=published draft=] on the [[W3C-CCG-PAGE]].
#### Final Report Stage
* When a [=community report=] is final, and work on that version is complete or a hand-off to a WG is imminent, the [=work item=] editors finalize any IPR commitments.
* The chairs review the [=published draft=] for consideration as a [=final report=] and post the proposal to become a [=final report=] an email to the CCG discussion list for approval.
* Once proposed, the community group will discuss it for a period of at least one week. This discussion may take place on the mailing list as well as on the regular conference call at the Chairs discretion.
* If there is sufficient community support for the [=published draft=] and there are no principled objections, the chairs at their discretion will submit the [=published draft=] to the W3C staff as a [=final report=].
* W3C Staff have final approval for all [=final report=] listed in the [[W3C-CCG-PAGE]].
* If accepted by the W3C staff, the [=ccg repository=] description will be changed to “FINAL REPORT:” and the [=work item=] is now closed.
### Ongoing community draft stages
Propose a CG [=work item=] with the intent to make it an [=ongoing community draft=] (such as a CG Registry). The proposal would pass per the CG's documented consensus process.
W3C leadership may propose a [=ongoing community draft=] process, in which case this would be revised to include that.
Any normative registry work items should be chartered by a W3C working group and shall be run according to that charter. Charter should include plans for releasing snapshots of the [=work item=].