Skip to content

Commit 8e143c1

Browse files
deniaksideshowbarkerdarobindontcallmedomiherman
authored
Move files from w3c.github.io (#295)
Moving documentation from w3c.github.io to w3c/guide --------- Co-authored-by: Michael[tm] Smith <[email protected]> Co-authored-by: Robin Berjon <[email protected]> Co-authored-by: Dominique Hazael-Massieux <[email protected]> Co-authored-by: Ivan Herman <[email protected]> Co-authored-by: tripu <[email protected]> Co-authored-by: Gerald Oskoboiny <[email protected]> Co-authored-by: Coralie Mercier <[email protected]> Co-authored-by: plehegar <[email protected]> Co-authored-by: Denis Ah-Kang <[email protected]> Co-authored-by: Jeffrey Yasskin <[email protected]> Co-authored-by: tmichel07 <[email protected]> Co-authored-by: Wendy Seltzer <[email protected]> Co-authored-by: Marcos Cáceres <[email protected]> Co-authored-by: Marcos Cáceres <[email protected]> Co-authored-by: ashimura <[email protected]> Co-authored-by: tripu <[email protected]> Co-authored-by: Vivien Lacourba <[email protected]> Co-authored-by: Frederik <[email protected]> Co-authored-by: grossdm <[email protected]> Co-authored-by: RealJoshue108 <[email protected]> Co-authored-by: Wendy Seltzer <[email protected]> Co-authored-by: Francois Daoust <[email protected]> Co-authored-by: Caen De Silva <[email protected]> Co-authored-by: Vivien Lacourba <[email protected]>
1 parent 3f6773b commit 8e143c1

11 files changed

+1802
-0
lines changed

‎github/backup.html

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="utf-8">
5+
<meta name="viewport" content="width=device-width">
6+
<title>GitHub organizations backups</title>
7+
<link rel="stylesheet" href="css/wgio.css">
8+
</head>
9+
<body>
10+
<header>
11+
<h1>GitHub organizations backups</h1>
12+
</header>
13+
<nav>
14+
<a href="/">Home</a>
15+
•
16+
<a href="https://github.com/w3c/">Repositories</a>
17+
•
18+
<a href="https://help.github.com/">GitHub Help</a>
19+
</nav>
20+
21+
<main>
22+
<p>
23+
W3C relies on <a href="https://rewind.com/">Rewind</a> to backup the different GitHub organizations the groups depend on.
24+
</p>
25+
<p>
26+
Rewind runs daily backups of all the repositories, including metadata and provides a way to restore a repository if the GitHub support is not able to help.
27+
</p>
28+
<section>
29+
<h3>Rewind App (GitHub)</h3>
30+
<p>
31+
To start the backup process for a GitHub organization, the user <a href="https://github.com/w3cbot">w3cbot</a> <em>must</em> be <a href="https://knowledge.rewind.com/s/article/which-permissions-do-i-need-to-install-rewind">listed as one of the owners of the organization</a> so it can:
32+
<ul>
33+
<li>install the <a href="https://github.com/apps/rewind-app-github">Rewind App</a> to the organization
34+
<li>import the organization into rewind
35+
<li>restore a repository when needed
36+
</ul>
37+
38+
After inviting w3cbot, you may request <a href="mailto:[email protected]">sysreq</a> to add your organization to rewind.
39+
</p>
40+
</section>
41+
</main>
42+
<footer>
43+
<address><a href="https://github.com/w3c/w3c.github.io/">We are on GitHub</a></address>
44+
<p>
45+
<a href="https://www.w3.org/"><img src="img/w3c.svg" width="65" height="45" alt="W3C Logo"></a>
46+
</p>
47+
</footer>
48+
</body>
49+
</html>

‎github/best-practices.html

+300
Large diffs are not rendered by default.

‎github/faq.html

+292
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,292 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="utf-8">
5+
<meta name="viewport" content="width=device-width">
6+
<title>FAQ</title>
7+
<link rel="stylesheet" href="css/wgio.css">
8+
<link rel="icon" type="image/x-icon" href="//labs.w3.org/favicon.ico">
9+
</head>
10+
<body class="targetable">
11+
<header>
12+
<h1>FAQ</h1>
13+
</header>
14+
<nav>
15+
<a href="/">Home</a>
16+
•
17+
<a href="https://github.com/w3c/">Repositories</a>
18+
•
19+
<a href="https://help.github.com/">GitHub Help</a>
20+
</nav>
21+
22+
<nav class="internal">
23+
<ul>
24+
<li>
25+
<a href="#starting">Getting started</a>
26+
<ul>
27+
<li><a href="#drafts">Informal drafts in your personal account</a></li>
28+
<li><a href="#repos">Hosting a repository within the <code>w3c</code> organisation</a></li>
29+
<li><a href="#steps">Detailed steps for <em>staff contacts</em> to create a repo</a></li>
30+
</ul>
31+
</li>
32+
<li>
33+
<a href="#integration">W3C integration</a>
34+
<ul>
35+
<li><a href="#mail">GitHub and W3C mailing lists</a></li>
36+
<li><a href="#contributors">Contributor management</a></li>
37+
</ul>
38+
</li>
39+
<li>
40+
<a href="#policy">Policy</a>
41+
<ul>
42+
<li><a href="#archiving">How do we ensure archiving of work done on GitHub?</a></li>
43+
<li><a href="#alternatives">May I use w3.org-hosted CVS or Mercurial instead?</a></li>
44+
<li><a href="#others">What about serving specs using a third-party tool?</a></li>
45+
<li><a href="#host">Will the W3C host an instance of RawGit or a similar service?</a></li>
46+
<li><a href="#issues">Should we use GitHub for issue management too?</a></li>
47+
<li><a href="#ipr">How do we manage IPR with specs authored on GitHub?</a></li>
48+
<li><a href="#trolls">What shall I do about trolls and spam on GitHub?</a></li>
49+
</ul>
50+
</li>
51+
</ul>
52+
</nav>
53+
54+
<main>
55+
<p>
56+
<a href="https://git-scm.com/">Git</a> is a popular, open-source distributed version control
57+
system, commonly used with <a href="https://github.com/">GitHub</a> as a convenient central host
58+
of repositories, along with wiki documentation, pull request management and issue tracking.
59+
Several W3C groups are using GitHub infrastructure for specification and test authoring
60+
workflows. Below we include some suggested steps for getting started and answers to some
61+
frequently asked questions about using GitHub for W3C spec work.
62+
</p>
63+
64+
<section id="starting">
65+
<h2>Getting started <a href="#starting">&#x1F517;</a></h2>
66+
67+
<section id="drafts">
68+
<h3>Informal drafts in your personal account <a href="#drafts">&#x1F517;</a></h3>
69+
<p>
70+
Getting started individually obviously doesn't require any approval process. Create an
71+
informal draft (using ReSpec makes it easy) by starting a new repository with your personal
72+
GitHub account. We strongly recommend one repository per document, unless you really
73+
know why you're doing it differently.
74+
</p>
75+
<p>
76+
You can just publish HTML as you normally would simply by setting up
77+
<a href="https://github.com/blog/2228-simpler-github-pages-publishing">GitHub Pages</a>
78+
to use the default branch, <code>main</code>.</p>
79+
<p>⚠️ <strong>NB:</strong> <a
80+
href="https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/">GitHub
81+
Pages can serve content off of <em>one branch and one directory only</em></a>&nbsp;&mdash;&nbsp;if
82+
your repo is hosting different specs, or different versions of the same spec, you will have to
83+
either cram all those documents into that branch/directory (and adapt your workflow around that
84+
file structure) or serve your pages in a different way (eg, setting your own web server or
85+
<a href="#others">using some kind of hosting provider</a>).</p>
86+
</section>
87+
88+
<section id="repos">
89+
<h3>Hosting a repository within the <code>w3c</code> organisation <a href="#repos">&#x1F517;</a></h3>
90+
<p>
91+
W3C projects include W3C staff selected projects as well as W3C Working (Interest) Group projects.
92+
It is possible that we decide to assess other group's requests to host a given repository.
93+
In any case, a prerequisite would be identifying the owner(s) either by name or by e-mail address.
94+
Refer to <a href="https://www.w3.org/2016/04/cg-support/#what">the Guidebook for Community Groups</a>
95+
for more information.
96+
</p>
97+
<ol>
98+
<li>
99+
Your Team Contact should become (if they're not already) a part of the
100+
<a href="https://github.com/organizations/w3c/settings/owners">Owners Team</a> of the W3C
101+
organisation. (Ask any of the current owners directly, or ask on &amp;sysreq. This is only
102+
for W3C Staff.)
103+
</li>
104+
<li>
105+
If there is no GitHub team roughly matching the group that will be pushing to that
106+
repository, the Team Contact should create a new team for the editors who will be
107+
contributing to the document, and give that team push and pull access.
108+
</li>
109+
<li>
110+
W3C staff (or Team Contacts of the group) create a new repository for each document
111+
(each deliverable, it can of course contain multiple resources).
112+
Add each such repository to the GitHub team so that the contributors
113+
all have push access. Other people can suggest changes by submitting pull requests (in
114+
fact, editors can do that too to enable reviewing before commits, if desired), but not
115+
every contributor will be given direct commit access.
116+
</li>
117+
</ol>
118+
</section>
119+
120+
<section id="steps">
121+
<h3>Detailed steps for <em>staff contacts</em> to create a repo <a href="#steps">&#x1F517;</a></h3>
122+
<p>
123+
<strong>
124+
The preferred way to create new repositories is by using
125+
the <a href="https://labs.w3.org/repo-manager/">W3C Repository Manager</a>, in particular this page:
126+
<a href="https://labs.w3.org/repo-manager/repo/new"><code>labs.w3.org/repo-manager/repo/new</code></a>.
127+
</strong>
128+
</p>
129+
<p>Follow the instructions below only if for some reason you can't use the W3C Repository Manager for this.</p>
130+
<ol>
131+
<li>
132+
Let's say you're working on the unicorn spec. You head to <a
133+
href="https://github.com/new">https://github.com/new</a> (which is linked as "New
134+
repository" from the home page). Under Owner you pick "w3c" (which you should have access
135+
to, if not ask someone on IRC) and under repo name you pick "unicorn". Enter a
136+
description, keep it public, initialise with a README, don't pick a .gitignore or a
137+
license.
138+
</li>
139+
<li>
140+
If you need to create a new team, go to <a
141+
href="https://github.com/organizations/w3c/teams/new">https://github.com/organizations/w3c/teams/new</a>.
142+
Give the team a name ("Unicorn Editors") and grant them "Push &amp; Pull" (no need for
143+
admin). Save the team. Under "Members", just start typing the user names for the editors,
144+
you'll get a drop down suggesting people. Once you've added them all, under repository
145+
start typing "unicorn" and you should see w3c/unicorn listed. Pick that.
146+
</li>
147+
<li>
148+
That will give you a <code>https://github.com/w3c/unicorn</code> with fully configured
149+
access.
150+
</li>
151+
</ol>
152+
</section>
153+
154+
</section>
155+
156+
<section id="integration">
157+
<h2>W3C integration <a href="#integration">&#x1F517;</a></h2>
158+
159+
<section id="mail">
160+
<h3>GitHub and W3C mailing lists <a href="#mail">&#x1F517;</a></h3>
161+
<p>
162+
To have notification to the mail list at opening of new bugs/issues and modification of
163+
existing ones from GitHub, you may use the <a
164+
href="https://github.com/dontcallmedom/github-notify-ml/">github notification solution</a>
165+
designed by Dominique Hazael-Massieux.
166+
</p>
167+
</section>
168+
169+
<section id="contributors">
170+
<h3>Contributor management <a href="#contributors">&#x1F517;</a></h3>
171+
<p>
172+
If you wish to accept pull requests from potentially arbitrary contributors but you need to
173+
ensure that they have signed up to the IPR terms, see the
174+
<a href="repo-management.html">Contributor Management</a> section.
175+
</p>
176+
</section>
177+
178+
</section>
179+
180+
<section id="policy">
181+
<h2>Policy <a href="#policy">&#x1F517;</a></h2>
182+
183+
<section id="archiving">
184+
<h3>How do we ensure archiving of work done on GitHub? <a href="#archiving">&#x1F517;</a></h3>
185+
<p>
186+
As usual, publication of Working Drafts and Recommendations into w3.org/TR/ will be done by
187+
your Group by copying snapshots which satisfy pubrules into the appropriate space, with
188+
W3C-guaranteed archiving.
189+
</p>
190+
<p>
191+
Because Git itself decentralises archiving of every change (every user clones all history),
192+
backups of version history of Git repositories are straightforward (since in fact every user
193+
of the repository has a backup). A specific tool to maintain a full backup of the W3C
194+
organisation is being developed, called <a
195+
href="https://github.com/w3c/gh-backup">gh-backup</a>.
196+
</p>
197+
<p>
198+
Content that is not part of the repositories themselves (issues, wikis, pull requests, etc.)
199+
are backed up as events to the <a href="https://github.com/w3c/pheme">Pheme</a> system (for
200+
the whole organisation). A Pheme instance is currently
201+
<a href="https://labs.w3.org/pheme/">running in beta</a>; and some of the
202+
recent events can be viewed in the <a href="https://labs.w3.org/midgard/">Midgard
203+
instance</a>. The full data can be made exploitable as it is all sorted and
204+
indexable.
205+
</p>
206+
</section>
207+
208+
<section id="alternatives">
209+
<h3>May I use w3.org-hosted CVS or Mercurial instead? <a href="#alternatives">&#x1F517;</a></h3>
210+
<p>No. Those are old services that are being deprecated.</p>
211+
</section>
212+
213+
<section id="others">
214+
<h3>What about serving specs using a third-party tool? <a href="#others">&#x1F517;</a></h3>
215+
<p>It is best to avoid these services and to either keep all documents that need to be displayed as web
216+
pages in the branch that GitHub Pages is serving, set up a proper web server, or use a hosting provider.</p>
217+
<p>In the past, some groups used <a href="https://rawgit.com/">RawGit</a> to serve their HTML
218+
documents with the appropriate MIME type, and from more than one branch (because of
219+
<a href="#drafts">these limitations of GitHub Pages</a>).
220+
That service (RawGit) is now defunct.</p>
221+
<p>Nowadays, if you absolutely need such a service, we would probably suggest the following two options
222+
&nbsp;&mdash;&nbsp;with the caveat that <em>it is just a recommendation that comes with no support nor
223+
guarantee</em>, since we do <em>not</em> control these services:</p>
224+
<ul>
225+
<li><a href="https://www.staticaly.com/">Staticaly</a>. By default, staticaly's cache is set for
226+
<em>1 year</em>, except for the files under the <code>main</code> branch. If you need the latest
227+
changes, you may append the following query string <code>?env=dev</code> to the URL.
228+
<li><a href="https://raw.githack.com/">raw.githack.com</a>. The UI of this service gives you URLs for
229+
production (1 year cache, no traffic limit) and development (changes reflected within minutes, low-traffic
230+
only) you can use depending on your needs. <strong>Note</strong>: this service
231+
does warn that excessive traffic to development URLs will be throttled, so use it with caution.
232+
</ul>
233+
<p>The reason to opt for the services above is that others, like
234+
<a href="https://htmlpreview.github.io/">HTMLPreview</a>, either rely on client-side JavaScript to
235+
generate the page dynamically, are limited to GH repositories only, or alter the pages or the links
236+
within them in some way.</p>
237+
</section>
238+
239+
<section id="host">
240+
<h3>Will the W3C host an instance of RawGit or a similar service? <a href="#host">&#x1F517;</a></h3>
241+
<p>No, the Systems Team is <em>not</em> planning to offer a similar service in the foreseeable
242+
future.</p>
243+
</section>
244+
245+
<section id="issues">
246+
<h3>Should we use GitHub for issue management too? <a href="#issues">&#x1F517;</a></h3>
247+
<p>
248+
Issue-management tooling is entirely up to groups to choose. That being said, the same notes
249+
apply as for the previous question: if you wish to communicate with a broader community,
250+
GitHub is usually the better option.
251+
</p>
252+
</section>
253+
254+
<section id="ipr">
255+
<h3>How do we manage IPR with specs authored on GitHub? <a href="#ipr">&#x1F517;</a></h3>
256+
<p>
257+
In general, in the same way as for any other contribution intake mechanism. GitHub only
258+
tends to be singled out because it often leads to more contributions.
259+
</p>
260+
<p>
261+
See <a href="repo-management.html">Contributor Management</a> for a tool that is available
262+
to automate that process.
263+
</p>
264+
</section>
265+
266+
<section id="trolls">
267+
<h3>What shall I do about trolls and spam on GitHub? <a href="#trolls">&#x1F517;</a></h3>
268+
<p>
269+
GitHub staff are usually quick to respond to spam or uncivic behaviour on their platform.
270+
When a particular GitHub account is repeatedly causing trouble in a W3C repository, a good
271+
first step is to <strong>report the account</strong> to GitHub.
272+
To do so, go to that user's profile page (eg, <code>https://github.com/supertroll</code>),
273+
click &ldquo;Block or report user&rdquo;, and then &ldquo;Report abuse&rdquo;.
274+
If after a while the account is not suspended by GitHub and spam persists, it is possible
275+
to <strong>block the account</strong> to prevent all interaction with the repository in
276+
the future.
277+
(<a href="mailto:[email protected]">Write W3C's sysreq</a> if you don't have permissions to
278+
block the account yourself.)
279+
</p>
280+
</section>
281+
282+
</section>
283+
284+
</main>
285+
<footer>
286+
<address><a href="https://github.com/w3c/w3c.github.io/">We are on GitHub</a></address>
287+
<p>
288+
<a href="https://www.w3.org/"><img src="img/w3c.svg" width="65" height="45" alt="W3C Logo"></a>
289+
</p>
290+
</footer>
291+
</body>
292+
</html>

0 commit comments

Comments
 (0)