Skip to content

Commit 5f2f961

Browse files
vivienlacourbavivienlacourba
authored
Convert W3C on GitHub pages to the new design (#299)
This is a follow-up of #267 and #297.
1 parent ec5a65a commit 5f2f961

26 files changed

+978
-1812
lines changed

‎README.md

+2-5
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ The general edition of the Guidebook is managed by [@w3c/guidebook](https://gith
2525
* How to do wide review.
2626
* [/editor/](editor)
2727
* How to author a specification, including ReSpec or other spec making programs.
28+
* [/github/](github)
29+
* How to use Git and GitHub at W3C.
2830
* [/manual-of-style/](manual-of-style)
2931
* The W3C Manual of Style for editors.
3032
* [/meetings/](meetings)
@@ -45,9 +47,4 @@ The general edition of the Guidebook is managed by [@w3c/guidebook](https://gith
4547
* [/other/](other)
4648
* Related to [permanent groups](https://www.w3.org/groups/).
4749

48-
# Related repositories
49-
* [//w3c.github.io](https://github.com/w3c/w3c.github.io)
50-
* How to use Git and GitHub at W3C.
51-
* This repository is not exposed through [the Guidebook](https://www.w3.org/guide/).
52-
5350
Note: now that we have a repository for the guidebook, simply add your documentation to it, rather than creating new repositories.

‎editor/resources.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ toc: true
5656
### GitHub
5757

5858
* Initial instructions for GitHub beginners:
59-
* [W3C on GitHub](https://w3c.github.io/)
59+
* [W3C on GitHub](../github/)
6060

6161
### For Editor's role
6262

‎github/backup.html

-49
This file was deleted.

‎github/backup.md

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
title: GitHub organizations backups
3+
toc: false
4+
---
5+
W3C relies on [Rewind](https://rewind.com/) to backup the different GitHub organizations the groups depend on.
6+
7+
Rewind runs daily backups of all the repositories, including metadata and provides a way to restore a repository if the GitHub support is not able to help.
8+
9+
## Rewind App (GitHub)
10+
11+
To start the backup process for a GitHub organization, the user [w3cbot](https://github.com/w3cbot) **must** be [listed as one of the owners of the organization](https://knowledge.rewind.com/s/article/which-permissions-do-i-need-to-install-rewind) so it can:
12+
13+
- Install the [Rewind App](https://github.com/apps/rewind-app-github) to the organization
14+
- Import the organization into Rewind
15+
- Restore a repository when needed
16+
17+
After inviting w3cbot, you may request [sysreq](mailto:[email protected]) to add your organization to Rewind.

‎github/best-practices.html

-300
This file was deleted.

‎github/best-practices.md

+197
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
---
2+
title: Best practices and recommended tools
3+
toc: true
4+
---
5+
6+
## For all GitHub users {#all}
7+
8+
### Enable two-factor authentication (2FA) {#mfa}
9+
10+
[Two-factor authentication, or 2FA](https://help.github.com/articles/about-two-factor-authentication/), is an extra layer of security used when logging into websites or apps to protect your online identity. With 2FA, you have to log in with your username and password and provide another form of authentication that only you know or have access to. We encourage all users to enable 2FA in as many services and applications as they use for which this feature is available — starting with GitHub.
11+
12+
You can set it up here: [`github.com/settings/security`](https://github.com/settings/security).
13+
14+
### Own your code {#own}
15+
16+
The repositories you contribute to should ideally have a file [`.github/CODEOWNERS`](https://help.github.com/articles/about-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).
17+
18+
(If that file is missing, point the maintainer of the repository to these two sections: [*§ settings*](#settings) and [*§ GitHub boilerplate files*](#boilerplate).)
19+
20+
### Submit atomic PR's {#atomic}
21+
22+
Your PR's should tend to be small, and contain *one* bugfix or new feature only.
23+
24+
### Make sure you receive notifications {#notifications}
25+
26+
It is recommended that all users automatically subscribe to [notifications](https://help.github.com/articles/managing-your-notifications/) from new W3C repositories. If/when a new repository is of no interest to them, the user can easily unsubscribe from it.
27+
28+
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.
29+
30+
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.
31+
32+
Set up automatic watching of new repositories here: [`github.com/settings/notifications`](https://github.com/settings/notifications). If you receive too much noise, prune the list of repositories that you watch here: [`github.com/watching`](https://github.com/watching).
33+
34+
**Repository maintainers should *always* watch their repositories** and respond to changes, issues, PRs, etc.
35+
36+
### Delete your branches soon {#branches}
37+
38+
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.
39+
40+
To remove old branches from your clone of the repo, run this Git command from time to time:
41+
42+
```
43+
$ git remote prune origin
44+
```
45+
46+
## For project maintainers {#maintainers}
47+
48+
### Set up the repository well {#setup}
49+
50+
#### Set common settings {#settings}
51+
52+
Review `https://github.com/w3c/<REPO>/settings`:
53+
54+
- 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.
55+
- Set up **GitHub Pages** if necessary; select the right branch for that.
56+
- In `https://github.com/w3c/<REPO>/settings/branches`:
57+
58+
- Make sure the **default branch** is `main` or `gh-pages`.
59+
- Consider [enforcing code reviews for PR's](https://help.github.com/articles/enabling-required-reviews-for-pull-requests/), at least for the default branch.
60+
- 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).
61+
62+
#### Fill in common fields {#fields}
63+
64+
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).
65+
66+
Check out how those are set up [in Echidna](https://github.com/w3c/echidna), for example.
67+
68+
### Include sufficient metadata {#metadata}
69+
70+
#### Git special files {#git}
71+
72+
Have a [`.gitignore`](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring) (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:
73+
74+
```
75+
node_modules/
76+
npm-debug.log
77+
logs/
78+
```
79+
80+
See [an example](https://github.com/w3c/validate-repos/blob/main/.gitignore).
81+
82+
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](https://git-scm.com/docs/git-config#Documentation/git-config.txt-coreexcludesFile).
83+
84+
#### GitHub boilerplate files {#boilerplate}
85+
86+
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`](https://help.github.com/articles/about-readmes/) there.
87+
88+
Other useful files you may want to keep under that directory are these (in decreasing order of importance):
89+
90+
- [`CONTRIBUTING.md`](https://help.github.com/articles/setting-guidelines-for-repository-contributors/)
91+
- [`ISSUE_TEMPLATE.md` and `PULL_REQUEST_TEMPLATE.md`](https://help.github.com/articles/about-issue-and-pull-request-templates/)
92+
- [`CODEOWNERS`](https://help.github.com/articles/about-codeowners/)
93+
- [`CODE_OF_CONDUCT.md`](https://help.github.com/articles/adding-a-code-of-conduct-to-your-project/)
94+
95+
An exception to this rule is the file [`LICENSE.md`](https://help.github.com/articles/adding-a-license-to-a-repository/), which should be in the root directory of the project, [or else GitHub will not find it](https://github.com/benbalter/licensee/issues/250#issuecomment-353985847).
96+
97+
See [an example](https://github.com/w3c/validate-repos/blob/main/LICENSE.md).
98+
99+
#### W3C-specific metadata {#w3c}
100+
101+
Usually applicable only to repositories containing specs (*not* software).
102+
103+
See [the `w3c.json` file](w3c.json.md).
104+
105+
### Handle permissions well {#perms}
106+
107+
Make sure you list the right *teams* and *individuals* under “Collaborators & teams”:
108+
109+
```
110+
https://github.com/w3c/<REPO>/settings/collaboration
111+
```
112+
113+
In particular, be conservative about assigning editing (write) permissions and do so only for known collaborators.
114+
115+
### Make sure you receive vulnerability alerts {#vulns}
116+
117+
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](https://help.github.com/articles/about-security-alerts-for-vulnerable-dependencies/).
118+
119+
Enable vulnerability alerts in settings, here:
120+
121+
```
122+
https://github.com/w3c/<REPO>/settings#vulnerability-alerts-feature
123+
```
124+
125+
Once enabled, vulnerabilities will be shown highlighted in two places:
126+
127+
- At the top of the main page of the repo; ie `https://github.com/w3c/<REPO>`
128+
- On the *Dependency Graph* page; ie `https://github.com/w3c/<REPO>/network/dependencies`
129+
130+
Finally, make sure you are receiving *notifications* about vulnerability alerts: [`github.com/settings/notifications`](https://github.com/settings/notifications) (bottom of the page).
131+
132+
### Set up CI {#ci}
133+
134+
[Travis CI](https://travis-ci.com/) is our recommended tool to do CI; check out [our repos there](https://travis-ci.org/w3c/).
135+
136+
A particular example of Travis configuration (see links below for more information):
137+
138+
```yaml
139+
language: node_js
140+
node_js: # ☞ “Building a JavaScript and Node.js project”
141+
- "8"
142+
- "10"
143+
before_install: # ☞ “Build Stages”
144+
- npm install -g npm@latest
145+
before_script:
146+
- cp config.js.example config.js
147+
script:
148+
- npm run build
149+
after_script:
150+
- npm run coveralls
151+
notifications: # ☞ “Configuring Build Notifications”
152+
email: false
153+
irc:
154+
channels:
155+
- "irc.w3.org#pub"
156+
skip_join: true
157+
template:
158+
- "%{branch} by %{author} (%{build_url}): %{message}"
159+
```
160+
161+
Travis CI help pages referenced above:
162+
163+
- [Building a JavaScript and Node.js project](https://docs.travis-ci.com/user/languages/javascript-with-nodejs/)
164+
- [Build Stages](https://docs.travis-ci.com/user/build-stages/)
165+
- [Configuring Build Notifications](https://docs.travis-ci.com/user/notifications/)
166+
167+
See [an example of Travis report page](https://travis-ci.org/w3c/echidna).
168+
169+
The specifics of Travis configuration depend greatly on the language/platform and on the dependencies and tools involved. See [the documentation](https://docs.travis-ci.com/) or browse existing repositories using Travis to learn more.
170+
171+
### Set up Repository Manager {#repository-manager}
172+
173+
(Applicable only to repositories containing specs, *not* software.)
174+
175+
You may want to add your new repository containing a spec in the [W3C Repository Manager](https://labs.w3.org/repo-manager/). This is a tool that helps with IPR managements from public contributors; check with the Systeam if in doubt.
176+
177+
### Patrol branches often {#branches2}
178+
179+
See also [Delete your branches soon](#branches).
180+
181+
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.
182+
183+
### Assess the quality of your repo {#tools}
184+
185+
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:
186+
187+
- [`validate-repos`](https://github.com/w3c/validate-repos): a W3C tool, specific for repos containing specs (*not* software); see [the kind of report it produces](https://w3c.github.io/validate-repos/report.html)
188+
- [`forkability`](https://github.com/basicallydan/forkability/): an external project, useful for any kind of public repository with open source
189+
190+
## See also {#also}
191+
192+
- GitHub:
193+
- datree: [“Top 10 GitHub Best Practices”](https://www.datree.io/resources/github-best-practices)
194+
- Web Platform Tests: [“Introduction to GitHub”](https://web-platform-tests.org/writing-tests/github-intro.html)
195+
- i18n activity: [“Github guidelines for working with i18n documents”](https://w3c.github.io/i18n-activity/guidelines/github)
196+
- Git: [Git recipes & tricks](git.md)
197+
- Node.js: [best practices, recommended tools and template projects](https://github.com/w3c/nodejs) (public repo).

0 commit comments

Comments
 (0)