GitHub/Repository Creation

From Education & Outreach

[Draft]

This page describes in principle the steps involved and considerations for creating a Github Repository.

Multiple vs. Single Repos

The standard approach is to be as granular as possible – so one repository per deliverable. A deliverable can contain multiple pages. Having multiple pages in one repository is especially important when the pages share a common navigation or are heavily interlinked.

Disadvantage of using multiple repositories: W3C has _a lot_ of repositories (360 at the moment) which means that it is very hard to find the correct repository if there are many. (On the other hand, we might be long beyond that threshold.) EO has put links to repositories, and specific documents in repositories, in place to help with this problem.

Only multiple repositories allow having issues for specific deliverables. Else you have to manually tag and track issues to get a good overview, which might be less practical.

Steps to create a GitHub Repository

You should always follow the following steps to ensure that participants find similar repositories and know their way to contribute.

  • Visit this page to create a repository.
  • Make sure the owner is W3C.
  • Name it “wai-” plus a descriptive short name e.g. “wai-quickref”, “wai-quick-start”
    • I personally would try to avoid dashes after ”wai-”, but that is my personal preference.
    • If you change the name afterwards, all links to the project will break. There are no redirects. This is final. Beware! (If you really need to change it, you can fork the repository to the new name, then add warnings and links to the old one. But it is not what we want to do in general.)
  • Enter a short description.
  • Set it to public.
  • Check “Initialize this repository with a README”.
  • Add .gitignore to your liking (or don’t)
  • Add no license to the project. (Afaik W3C’s licence is not in the drop down anyway.)

---
After you have clicked “Create repository”:

  • Create a new file named w3c.json with this content (-35532 if not EOWG-managed resource):
{
      "group":      35532
  ,   "contacts":   ["slhenry"]
  ,   "repo-type":  "article"
  }

W3C json info with more info

---

Enable GitHub.io preview:

  • Click on Settings
  • Scroll down until you see a block that has the heading “Github Pages”
  • From the Source dropdown (currently shows “none”) select either master branch master branch /docs folder.

---
Add the repository to the WAI-EO GitHub repos listing

Using GitHub Pages

To use the Github pages functionality, following steps are required:

  1. Make sure all documents have a <base href="https://www.w3.org/WAI/path/to/the/directory/of/the/file"> element inside of <head>.
  2. Go to the main GitHub page of your repository.
    1. There, click on the Branch: master dropdown.
    2. In the Find or create a Branch… text field, enter gh-pages & press enter.
      • All your files are copied to the new branch.
  3. Click on 2 branches on the top of the page.
  4. Click on the Change default branch button.
  5. Select gh-pages from the drop down.
  6. Click update and confirm that you’re sure.
  7. All changes and commits should now go to that gh-pages branch, you have to switch branches locally on your computer as well, if you have checked out the repository.
  8. You should now find your files at https://w3c.github.io/wai-{reponame}/{path}/{to}/{filename}.{ext} – note that you might need to make a change to one of the files in the repository (like README) to make the resource available. From than on all updates should be reflected quickly after they have been committed.

(Optional:) Delete master branch:

Note: This will break certain links, like rawgit links if they have /master/ in their URL.

  1. Go to the main GitHub page of your repository.
  2. Click on 2 branches on the top of the page.
  3. Click on the trash icon (Delete this branch) next to the master branch.
Retrieved from "https://www.w3.org/WAI/EO/wiki/index.php?title=GitHub/Repository_Creation&oldid=26136"