Best practices and recommended tools

For all GitHub users 🔗

Own your code 🔗

The repositories you contribute to should ideally have a file .github/CODEOWNERS. If that is so, suggest to the maintainer edits to that file so that you will be automatically assigned PR reviews for those PR's that will affect the areas or files that you “own” (ie, that you are usually responsible for).

(If that file is missing, point the maintainer of the repository to these two sections: § settings and § GitHub boilerplate files.)

Submit atomic PR's 🔗

Your PR's should tend to be small, and contain one bugfix or new feature only.

Make sure you receive notifications 🔗

It is recommended that all users automatically subscribe to notifications from new W3C repositories. If/when a new repository is of no interest to them, the user can easily unsubscribe from it.

The “danger” of missing important notifications if one does not subscribe to all of them is higher than the slight annoyance of having to manually unsubscribe from (most) new repositories every time.

Users can choose whether to receive those notifications via e-mail, as alerts on the web UI of GH, or in both ways at the same time.

Set up automatic watching of new repositories here: github.com/settings/notifications. If you receive too much noise, prune the list of repositories that you watch here: github.com/watching.

Repository maintainers should always watch their repositories and respond to changes, issues, PRs, etc.

Delete your branches soon 🔗

Branches you create to submit PRs should be deleted as soon as the PR is resolved (either merged or closed for other reasons). Make a point of deleting a branch when you see its corresponding PR has been merged.

To remove old branches from your clone of the repo, run this Git command from time to time:

$ git remote prune origin

For project maintainers 🔗

Set up the repository well 🔗

Set common settings 🔗

Review https://github.com/w3c/<REPO>/settings:

  • Does your project use wikis or projects? If not, disabling those options will reduce some cognitive load, un-clutter the web UI, and prevent absent-minded collaborators from contributing wiki pages or other stuff that nobody is using nor paying attention to.
  • Set up GitHub Pages if necessary; select the right branch for that.
  • In https://github.com/w3c/<REPO>/settings/branches:
  • In https://github.com/w3c/<REPO>/settings/installations, under Services, you may want to add a handy service; like an IRC notifier, or a Twitter bridge (depending on the nature of your repository, of course).

Fill in common fields 🔗

In particular, the three fields that appear at the top of the main page of the repo: description (something short), website (often pointing to GitHub Pages) and topics (tags).

Check out how those are set up in Echidna, for example.

Include sufficient metadata 🔗

Git special files 🔗

Have a .gitignore (hidden file) in the root directory of your repo to list files and directories that you do not want to keep under version control. Typically something along the lines of:

node_modules/
npm-debug.log
logs/

See an example.

Ideally, this file should not contain filenames or patterns that are associated to specific OS's, IDE's or editors; eg .DS_Store (MacOS), Thumbs.db (Windows), *~ (emacs). The other contributors don't need to know about the different types of droppings your tools produce, and there are cleaner ways to ignore files locally, like configuring your Git to do so.

GitHub boilerplate files 🔗

To keep the root directory of the repository clean and manageable, store as many metadata files under .github/ as possible. You should certainly have a README.md there.

Other useful files you may want to keep under that directory are these (in decreasing order of importance):

An exception to this rule is the file LICENSE.md, which should be in the root directory of the project, or else GitHub will not find it.

See an example.

W3C-specific metadata 🔗

Usually applicable only to repositories containing specs (not software).

See the w3c.json file.

Handle permissions well 🔗

Make sure you list the right teams and individuals under “Collaborators & teams”:

https://github.com/w3c/<REPO>/settings/collaboration

In particular, be conservative about assigning editing (write) permissions and do so only for known collaborators.

Make sure you receive vulnerability alerts 🔗

Usually applicable only to repositories containing software (not specs), and assuming the language/platform detected in the repository is understood and supported by GitHub; find out in their help pages.

Enable vulnerability alerts in settings, here:

https://github.com/w3c/<REPO>/settings#vulnerability-alerts-feature

Once enabled, vulnerabilities will be shown highlighted in two places:

  • At the top of the main page of the repo; ie https://github.com/w3c/<REPO>
  • On the Dependency Graph page; ie https://github.com/w3c/<REPO>/network/dependencies

Finally, make sure you are receiving notifications about vulnerability alerts: github.com/settings/notifications (bottom of the page).

Set up CI 🔗

Travis CI is our recommended tool to do CI; check out our repos there.

A particular example of Travis configuration (see links below for more information):

language: node_js
node_js:                            # ☞ “Building a JavaScript and Node.js project”
  - "8"
  - "10"
before_install:                     # ☞ “Build Stages”
  - npm install -g npm@latest
before_script:
  - cp config.js.example config.js
script:
  - npm run build
after_script:
  - npm run coveralls
notifications:                      # ☞ “Configuring Build Notifications”
  email: false
  irc:
    channels:
      - "irc.w3.org#pub"
    skip_join: true
    template:
      - "%{branch} by %{author} (%{build_url}): %{message}"

Travis CI help pages referenced above:

See an example of Travis report page.

The specifics of Travis configuration depend greatly on the language/platform and on the dependencies and tools involved. See the documentation or browse existing repositories using Travis to learn more.

Set up Repository Manager 🔗

(Applicable only to repositories containing specs, not software.)

You may want to add your new repository containing a spec in Repository Manager (aka Ash-Nazg). This is a tool that helps with IPR managements from public contributors; check with the Systeam if in doubt.

Patrol branches often 🔗

See also Delete your branches soon.

From time to time, check the list of all branches in the project, https://github.com/w3c/<REPO>/branches/all, and delete the ones that aren't being used; branches that are not ahead of the default branch, and branches associated to PRs that are either merged or closed already, are definitely good candidates for removal. If in doubt, ask the author of the branch.

Assess the quality of your repo 🔗

From time to time, run tools like these to evaluate how well your repositories are maintained, and whether they are outdated or missing some metadata or files:

See also 🔗