For all GitHub users 🔗
Own your code 🔗
The repositories you contribute to should ideally have a file
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:
If you receive too much noise, prune the list of repositories that you watch here:
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 🔗
- 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.
- Make sure the default branch is
- Consider enforcing code reviews for PR's, at least for the default branch.
- Make sure the default branch is
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 🔗
(hidden file) in the root directory of your repo to list files and directories that you do not want to keep under version
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
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
You should certainly have a
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
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).
Handle permissions well 🔗
Make sure you list the right teams and individuals under “Collaborators & teams”:
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:
Once enabled, vulnerabilities will be shown highlighted in two places:
- At the top of the main page of the repo; ie
- On the Dependency Graph page; ie
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):
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 the W3C Repository Manager. 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,
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 🔗
- datree: “Top 10 GitHub Best Practices”
- Web Platform Tests: “Introduction to GitHub”
- i18n activity: “Github guidelines for working with i18n documents”
- Git: Git recipes & tricks
- Node.js: best practices, recommended tools and template projects (public repo).