-
Notifications
You must be signed in to change notification settings - Fork 40
/
faq.html
292 lines (271 loc) · 14.6 KB
/
faq.html
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
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width">
<title>FAQ</title>
<link rel="stylesheet" href="css/wgio.css">
<link rel="icon" type="image/x-icon" href="//labs.w3.org/favicon.ico">
</head>
<body class="targetable">
<header>
<h1>FAQ</h1>
</header>
<nav>
<a href="/">Home</a>
•
<a href="https://github.com/w3c/">Repositories</a>
•
<a href="https://help.github.com/">GitHub Help</a>
</nav>
<nav class="internal">
<ul>
<li>
<a href="#starting">Getting started</a>
<ul>
<li><a href="#drafts">Informal drafts in your personal account</a></li>
<li><a href="#repos">Hosting a repository within the <code>w3c</code> organisation</a></li>
<li><a href="#steps">Detailed steps for <em>staff contacts</em> to create a repo</a></li>
</ul>
</li>
<li>
<a href="#integration">W3C integration</a>
<ul>
<li><a href="#mail">GitHub and W3C mailing lists</a></li>
<li><a href="#contributors">Contributor management</a></li>
</ul>
</li>
<li>
<a href="#policy">Policy</a>
<ul>
<li><a href="#archiving">How do we ensure archiving of work done on GitHub?</a></li>
<li><a href="#alternatives">May I use w3.org-hosted CVS or Mercurial instead?</a></li>
<li><a href="#others">What about serving specs using a third-party tool?</a></li>
<li><a href="#host">Will the W3C host an instance of RawGit or a similar service?</a></li>
<li><a href="#issues">Should we use GitHub for issue management too?</a></li>
<li><a href="#ipr">How do we manage IPR with specs authored on GitHub?</a></li>
<li><a href="#trolls">What shall I do about trolls and spam on GitHub?</a></li>
</ul>
</li>
</ul>
</nav>
<main>
<p>
<a href="https://git-scm.com/">Git</a> is a popular, open-source distributed version control
system, commonly used with <a href="https://github.com/">GitHub</a> as a convenient central host
of repositories, along with wiki documentation, pull request management and issue tracking.
Several W3C groups are using GitHub infrastructure for specification and test authoring
workflows. Below we include some suggested steps for getting started and answers to some
frequently asked questions about using GitHub for W3C spec work.
</p>
<section id="starting">
<h2>Getting started <a href="#starting">🔗</a></h2>
<section id="drafts">
<h3>Informal drafts in your personal account <a href="#drafts">🔗</a></h3>
<p>
Getting started individually obviously doesn't require any approval process. Create an
informal draft (using ReSpec makes it easy) by starting a new repository with your personal
GitHub account. We strongly recommend one repository per document, unless you really
know why you're doing it differently.
</p>
<p>
You can just publish HTML as you normally would simply by setting up
<a href="https://github.com/blog/2228-simpler-github-pages-publishing">GitHub Pages</a>
to use the default branch, <code>main</code>.</p>
<p>⚠️ <strong>NB:</strong> <a
href="https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/">GitHub
Pages can serve content off of <em>one branch and one directory only</em></a> — if
your repo is hosting different specs, or different versions of the same spec, you will have to
either cram all those documents into that branch/directory (and adapt your workflow around that
file structure) or serve your pages in a different way (eg, setting your own web server or
<a href="#others">using some kind of hosting provider</a>).</p>
</section>
<section id="repos">
<h3>Hosting a repository within the <code>w3c</code> organisation <a href="#repos">🔗</a></h3>
<p>
W3C projects include W3C staff selected projects as well as W3C Working (Interest) Group projects.
It is possible that we decide to assess other group's requests to host a given repository.
In any case, a prerequisite would be identifying the owner(s) either by name or by e-mail address.
Refer to <a href="https://www.w3.org/2016/04/cg-support/#what">the Guidebook for Community Groups</a>
for more information.
</p>
<ol>
<li>
Your Team Contact should become (if they're not already) a part of the
<a href="https://github.com/organizations/w3c/settings/owners">Owners Team</a> of the W3C
organisation. (Ask any of the current owners directly, or ask on &sysreq. This is only
for W3C Staff.)
</li>
<li>
If there is no GitHub team roughly matching the group that will be pushing to that
repository, the Team Contact should create a new team for the editors who will be
contributing to the document, and give that team push and pull access.
</li>
<li>
W3C staff (or Team Contacts of the group) create a new repository for each document
(each deliverable, it can of course contain multiple resources).
Add each such repository to the GitHub team so that the contributors
all have push access. Other people can suggest changes by submitting pull requests (in
fact, editors can do that too to enable reviewing before commits, if desired), but not
every contributor will be given direct commit access.
</li>
</ol>
</section>
<section id="steps">
<h3>Detailed steps for <em>staff contacts</em> to create a repo <a href="#steps">🔗</a></h3>
<p>
<strong>
The preferred way to create new repositories is by using
the <a href="https://labs.w3.org/repo-manager/">W3C Repository Manager</a>, in particular this page:
<a href="https://labs.w3.org/repo-manager/repo/new"><code>labs.w3.org/repo-manager/repo/new</code></a>.
</strong>
</p>
<p>Follow the instructions below only if for some reason you can't use the W3C Repository Manager for this.</p>
<ol>
<li>
Let's say you're working on the unicorn spec. You head to <a
href="https://github.com/new">https://github.com/new</a> (which is linked as "New
repository" from the home page). Under Owner you pick "w3c" (which you should have access
to, if not ask someone on IRC) and under repo name you pick "unicorn". Enter a
description, keep it public, initialise with a README, don't pick a .gitignore or a
license.
</li>
<li>
If you need to create a new team, go to <a
href="https://github.com/organizations/w3c/teams/new">https://github.com/organizations/w3c/teams/new</a>.
Give the team a name ("Unicorn Editors") and grant them "Push & Pull" (no need for
admin). Save the team. Under "Members", just start typing the user names for the editors,
you'll get a drop down suggesting people. Once you've added them all, under repository
start typing "unicorn" and you should see w3c/unicorn listed. Pick that.
</li>
<li>
That will give you a <code>https://github.com/w3c/unicorn</code> with fully configured
access.
</li>
</ol>
</section>
</section>
<section id="integration">
<h2>W3C integration <a href="#integration">🔗</a></h2>
<section id="mail">
<h3>GitHub and W3C mailing lists <a href="#mail">🔗</a></h3>
<p>
To have notification to the mail list at opening of new bugs/issues and modification of
existing ones from GitHub, you may use the <a
href="https://github.com/dontcallmedom/github-notify-ml/">github notification solution</a>
designed by Dominique Hazael-Massieux.
</p>
</section>
<section id="contributors">
<h3>Contributor management <a href="#contributors">🔗</a></h3>
<p>
If you wish to accept pull requests from potentially arbitrary contributors but you need to
ensure that they have signed up to the IPR terms, see the
<a href="repo-management.html">Contributor Management</a> section.
</p>
</section>
</section>
<section id="policy">
<h2>Policy <a href="#policy">🔗</a></h2>
<section id="archiving">
<h3>How do we ensure archiving of work done on GitHub? <a href="#archiving">🔗</a></h3>
<p>
As usual, publication of Working Drafts and Recommendations into w3.org/TR/ will be done by
your Group by copying snapshots which satisfy pubrules into the appropriate space, with
W3C-guaranteed archiving.
</p>
<p>
Because Git itself decentralises archiving of every change (every user clones all history),
backups of version history of Git repositories are straightforward (since in fact every user
of the repository has a backup). A specific tool to maintain a full backup of the W3C
organisation is being developed, called <a
href="https://github.com/w3c/gh-backup">gh-backup</a>.
</p>
<p>
Content that is not part of the repositories themselves (issues, wikis, pull requests, etc.)
are backed up as events to the <a href="https://github.com/w3c/pheme">Pheme</a> system (for
the whole organisation). A Pheme instance is currently
<a href="https://labs.w3.org/pheme/">running in beta</a>; and some of the
recent events can be viewed in the <a href="https://labs.w3.org/midgard/">Midgard
instance</a>. The full data can be made exploitable as it is all sorted and
indexable.
</p>
</section>
<section id="alternatives">
<h3>May I use w3.org-hosted CVS or Mercurial instead? <a href="#alternatives">🔗</a></h3>
<p>No. Those are old services that are being deprecated.</p>
</section>
<section id="others">
<h3>What about serving specs using a third-party tool? <a href="#others">🔗</a></h3>
<p>It is best to avoid these services and to either keep all documents that need to be displayed as web
pages in the branch that GitHub Pages is serving, set up a proper web server, or use a hosting provider.</p>
<p>In the past, some groups used <a href="https://rawgit.com/">RawGit</a> to serve their HTML
documents with the appropriate MIME type, and from more than one branch (because of
<a href="#drafts">these limitations of GitHub Pages</a>).
That service (RawGit) is now defunct.</p>
<p>Nowadays, if you absolutely need such a service, we would probably suggest the following two options
— with the caveat that <em>it is just a recommendation that comes with no support nor
guarantee</em>, since we do <em>not</em> control these services:</p>
<ul>
<li><a href="https://www.staticaly.com/">Staticaly</a>. By default, staticaly's cache is set for
<em>1 year</em>, except for the files under the <code>main</code> branch. If you need the latest
changes, you may append the following query string <code>?env=dev</code> to the URL.
<li><a href="https://raw.githack.com/">raw.githack.com</a>. The UI of this service gives you URLs for
production (1 year cache, no traffic limit) and development (changes reflected within minutes, low-traffic
only) you can use depending on your needs. <strong>Note</strong>: this service
does warn that excessive traffic to development URLs will be throttled, so use it with caution.
</ul>
<p>The reason to opt for the services above is that others, like
<a href="https://htmlpreview.github.io/">HTMLPreview</a>, either rely on client-side JavaScript to
generate the page dynamically, are limited to GH repositories only, or alter the pages or the links
within them in some way.</p>
</section>
<section id="host">
<h3>Will the W3C host an instance of RawGit or a similar service? <a href="#host">🔗</a></h3>
<p>No, the Systems Team is <em>not</em> planning to offer a similar service in the foreseeable
future.</p>
</section>
<section id="issues">
<h3>Should we use GitHub for issue management too? <a href="#issues">🔗</a></h3>
<p>
Issue-management tooling is entirely up to groups to choose. That being said, the same notes
apply as for the previous question: if you wish to communicate with a broader community,
GitHub is usually the better option.
</p>
</section>
<section id="ipr">
<h3>How do we manage IPR with specs authored on GitHub? <a href="#ipr">🔗</a></h3>
<p>
In general, in the same way as for any other contribution intake mechanism. GitHub only
tends to be singled out because it often leads to more contributions.
</p>
<p>
See <a href="repo-management.html">Contributor Management</a> for a tool that is available
to automate that process.
</p>
</section>
<section id="trolls">
<h3>What shall I do about trolls and spam on GitHub? <a href="#trolls">🔗</a></h3>
<p>
GitHub staff are usually quick to respond to spam or uncivic behaviour on their platform.
When a particular GitHub account is repeatedly causing trouble in a W3C repository, a good
first step is to <strong>report the account</strong> to GitHub.
To do so, go to that user's profile page (eg, <code>https://github.com/supertroll</code>),
click “Block or report user”, and then “Report abuse”.
If after a while the account is not suspended by GitHub and spam persists, it is possible
to <strong>block the account</strong> to prevent all interaction with the repository in
the future.
(<a href="mailto:[email protected]">Write W3C's sysreq</a> if you don't have permissions to
block the account yourself.)
</p>
</section>
</section>
</main>
<footer>
<address><a href="https://github.com/w3c/w3c.github.io/">We are on GitHub</a></address>
<p>
<a href="https://www.w3.org/"><img src="img/w3c.svg" width="65" height="45" alt="W3C Logo"></a>
</p>
</footer>
</body>
</html>