Skip to content

Commit

Permalink
Move files from w3c.github.io (#295)
Browse files Browse the repository at this point in the history 
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]>
  • Loading branch information
@deniak @sideshowbarker
@darobin @dontcallmedom @iherman @tripu @gosko @koalie @plehegar @jyasskin @tmichel07 @wseltzer @marcoscaceres @ashimura @vivienlacourba @mozfreddyb @Grossdm @RealJoshue108 @tidoust @caendesilva
25 people authored Jan 16, 2025
1 parent 3f6773b commit 8e143c1
Show file tree
Hide file tree
Showing 11 changed files with 1,802 additions and 0 deletions.
49 changes: 49 additions & 0 deletions github/backup.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width">
<title>GitHub organizations backups</title>
<link rel="stylesheet" href="css/wgio.css">
</head>
<body>
<header>
<h1>GitHub organizations backups</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>

<main>
<p>
W3C relies on <a href="https://rewind.com/">Rewind</a> to backup the different GitHub organizations the groups depend on.
</p>
<p>
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.
</p>
<section>
<h3>Rewind App (GitHub)</h3>
<p>
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:
<ul>
<li>install the <a href="https://github.com/apps/rewind-app-github">Rewind App</a> to the organization
<li>import the organization into rewind
<li>restore a repository when needed
</ul>

After inviting w3cbot, you may request <a href="mailto:[email protected]">sysreq</a> to add your organization to rewind.
</p>
</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>
300 changes: 300 additions & 0 deletions github/best-practices.html
View file

Large diffs are not rendered by default.

292 changes: 292 additions & 0 deletions github/faq.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,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">&#x1F517;</a></h2>

<section id="drafts">
<h3>Informal drafts in your personal account <a href="#drafts">&#x1F517;</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>&nbsp;&mdash;&nbsp;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">&#x1F517;</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 &amp;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">&#x1F517;</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 &amp; 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">&#x1F517;</a></h2>

<section id="mail">
<h3>GitHub and W3C mailing lists <a href="#mail">&#x1F517;</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">&#x1F517;</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">&#x1F517;</a></h2>

<section id="archiving">
<h3>How do we ensure archiving of work done on GitHub? <a href="#archiving">&#x1F517;</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">&#x1F517;</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">&#x1F517;</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
&nbsp;&mdash;&nbsp;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">&#x1F517;</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">&#x1F517;</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">&#x1F517;</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">&#x1F517;</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 &ldquo;Block or report user&rdquo;, and then &ldquo;Report abuse&rdquo;.
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>
Loading

0 comments on commit 8e143c1

Please sign in to comment.