CINXE.COM
FAQ
<!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:sysreq@w3.org">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>