Skip to content

Latest commit

 

History

History
102 lines (70 loc) · 4.9 KB

setting-up-github-repositories.md

File metadata and controls

102 lines (70 loc) · 4.9 KB
Raw

Setting up github repositories for specifications

This document tries to describe how we set up github repositories for specifications or specification-like documents. These documents are generally maintained in either bikeshed or respec.

Also see W3C's FAQ on using GitHub.

Naming the repository

The repository should be named with the shortname of your document.

Every W3C document has a "shortname", which is a short, memorable name for the document. The document's shortname should be all lowercase, and words should be separated by hyphens.

Structuring the repository

Structure your branch names without concern for any features offered by GitHub. In particular, don't commit source to a gh-pages branch. (In some cases automation may commit generated output to a gh-pages branch, though.) Note that some of our existing repositories do not follow this advice and commit respec source to a gh-pages branch.

This branch should contain only the source; files generated by bikeshed (or respec) should not be committed.

Configuring your Bikeshed document

Create a document named index.bs in your repository.

It should start with a <pre class=metadata> section like this:

<pre class=metadata>
Title: The title of your document
URL: https://w3ctag.github.io/your-repository-name/
Shortname: your-shortname
Repository: w3ctag/your-repository-name
Group: tag
Editor: Your Name, w3cid NNNNN, Company name https://company.com, your@email.address
Default Biblio Status: current
Markup Shorthands: markdown yes
Abstract: A description of your document.
</pre>

Your w3cid is the number at the end of the url when you navigate to https://www.w3.org/users/myprofile.

If the document has previously been published (as a Finding or a Working Group Note), add metadata pointing at the most recently published version:

TR: url-to-the-latest-published-version

Additional metadata for Findings

When we're working on a document that we intend to end up as a TAG Finding, the in-progress document is a Draft Finding.

Status: DRAFT-FINDING

Additional metadata for Notes

When we're working on a document that we intend to end up as a Working Group Note, the in-progress document is an Editor's Draft (ED). Bikeshed requires Editor's Drafts to have a level specified, but we don't use levels for TAG documents.

Status: ED
Level: none

Configuring github settings

After creating the repository, change the following aspects of its settings:

  1. In the Options tab, under Merge button, uncheck Allow merge commits
  2. In the Options tab, under GitHub Pages, set the Source:
    • for bikeshed specs, set it to gh-pages
    • for respec specs, set it to master or whatever the primary branch is (note that some older specs use gh-pages, but this is no longer needed)
  3. In the Branches tab, under Branch protection rules, choose Add rule. Create a rule matching master (or whatever the primary branch is), and check the two checkboxes Require linear history and Include administrators. (Also consider whether to check Require pull request reviews before merging or Require status checks to pass before merging.)

Configuring automatic running of bikeshed

For bikeshed specs, we set up autogeneration of the bikeshed output from the source using GitHub Actions. The source is (as described above) on the master branch (or whatever other name we use for the primary branch), and we set up automatic running of bikeshed to generate its output and commit it to the gh-pages branch. (Note that some of our existing repositories do not follow this advice and use Travis-CI for this.)

To set this up in your repository, follow these steps:

  1. Add this Makefile to your repository and name it Makefile.
  2. Create a .github/workflows/ directory and put deploy.yml in it.

If the primary branch of your repository is not named master, you'll need to edit deploy.yml to reflect this.

Note that these two files assume the build directory (where the built HTML goes) is named build. If you want to call it something else (e.g. out), you'll have to update both your Makefile and deploy.yml.

Configuring PR Preview

We have already set up PR Preview by using the steps:

  1. go to PR Preview GitHub App
  2. click Configure on the right
  3. Choose the @w3ctag organization
  4. choose to set it up for All repositories

This means that all we need to enable PR Preview is to add a .pr-preview.json, which is easiest to do by using the PR Preview setup helper and choosing the appropriate defaults there.