forked from w3c/w3c.github.io
-
Notifications
You must be signed in to change notification settings - Fork 0
/
best-practices.html
300 lines (290 loc) · 21 KB
/
best-practices.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width" />
<title>Best practices and recommended tools</title>
<link rel="stylesheet" href="css/wgio.css" />
<link rel="icon" type="image/x-icon" href="//labs.w3.org/favicon.ico" />
</head>
<body class="targetable">
<header>
<h1>Best practices and recommended tools</h1>
</header>
<nav>
<a href="/">Home</a>
•
<a href="https://github.com/w3c/">Repositories</a>
•
<a href="https://help.github.com/">GitHub Help</a>
</nav>
<nav class="internal">
<ul>
<li>
<a href="#all">For all GitHub users</a>
<ul>
<li><a href="#2fa">Enable two-factor authentication (2FA)</a></li>
<li><a href="#own"><em>Own</em> your code</a></li>
<li><a href="#atomic">Submit <em>atomic</em> PR's</a></li>
<li><a href="#notifications">Make sure you receive notifications</a></li>
<li><a href="#branches">Delete your branches soon</a></li>
</ul>
</li>
<li>
<a href="#maintainers">For project maintainers</a>
<ul>
<li>
<a href="#setup">Set up the repository well</a>
<ul>
<li><a href="#settings">Set common settings</a></li>
<li><a href="#fields">Fill in common fields</a></li>
</ul>
</li>
<li>
<a href="#metadata">Include sufficient metadata</a>
<ul>
<li><a href="#git">Git special files</a></li>
<li><a href="#boilerplate">GitHub boilerplate files</a></li>
<li><a href="#w3c">W3C-specific metadata</a></li>
</ul>
</li>
<li><a href="#perms">Handle permissions well</a></li>
<li><a href="#vulns">Make sure you receive vulnerability alerts</a></li>
<li><a href="#ci">Set up <abbr title="continuous integration">CI</abbr></a></li>
<li><a href="#repository-manager">Set up Repository Manager</a></li>
<li><a href="#branches2">Patrol branches often</a></li>
<li><a href="#tools">Assess the quality of your repo</a></li>
</ul>
</li>
<li>
<a href="#also">See also</a>
</li>
</ul>
</nav>
<main>
<section id="all">
<h2>For all GitHub users <a href="#all">🔗</a></h2>
<section id="2fa">
<h3>Enable two-factor authentication (2FA) <a href="#2fa">🔗</a></h3>
<p><a href="https://help.github.com/articles/about-two-factor-authentication/">Two-factor authentication, or 2FA</a>, 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.</p>
<p>You can set it up here: <a href="https://github.com/settings/security"><code>github.com/settings/security</code></a>.</p>
</section>
<section id="own">
<h3><em>Own</em> your code <a href="#own">🔗</a></h3>
<p>The repositories you contribute to should ideally have a file
<a href="https://help.github.com/articles/about-codeowners/"><code>.github/CODEOWNERS</code></a>.
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).</p>
<p>(If that file is missing, point the maintainer of the repository to these two sections:
<a href="#settings"><em>§ settings</em></a> and <a href="#boilerplate"><em>§ GitHub boilerplate files</em></a>.)</p>
</section>
<section id="atomic">
<h3>Submit <em>atomic</em> PR's <a href="#atomic">🔗</a></h3>
<p>Your PR's should tend to be small, and contain <em>one</em> bugfix or new feature only.</p>
</section>
<section id="notifications">
<h3>Make sure you receive notifications <a href="#notifications">🔗</a></h3>
<p>It is recommended that all users automatically subscribe to
<a href="https://help.github.com/articles/managing-your-notifications/">notifications</a> from new W3C repositories.
If/when a new repository is of no interest to them, the user can easily unsubscribe from it.</p>
<p>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.</p>
<p>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.</p>
<p>Set up automatic watching of new repositories here:
<a href="https://github.com/settings/notifications"><code>github.com/settings/notifications</code></a>.
If you receive too much noise, prune the list of repositories that you watch here:
<a href="https://github.com/watching"><code>github.com/watching</code></a>.</p>
<p><strong>Repository maintainers should <em>always</em> watch their repositories</strong> and respond to changes, issues, PRs, etc.</p>
</section>
<section id="branches">
<h3>Delete your branches soon <a href="#branches">🔗</a></h3>
<p>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.</p>
<p>To remove old branches from your clone of the repo, run this Git command from time to time:</p>
<pre>$ git remote prune origin</pre>
</section>
</section>
<section id="maintainers">
<h2>For project maintainers <a href="#maintainers">🔗</a></h2>
<section id="setup">
<h3>Set up the repository well <a href="#setup">🔗</a></h3>
<section id="settings">
<h4>Set common settings <a href="#settings">🔗</a></h4>
<p>Review <code>https://github.com/w3c/<REPO>/settings</code>:</p>
<ul>
<li>Does your project use <strong>wikis</strong> or <strong>projects</strong>? 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.</li>
<li>Set up <strong>GitHub Pages</strong> if necessary; select the right branch for that.</li>
<li>In <code>https://github.com/w3c/<REPO>/settings/branches</code>:
<ul>
<li>Make sure the <strong>default branch</strong> is <code>main</code> or <code>gh-pages</code>.</li>
<li>Consider <a href="https://help.github.com/articles/enabling-required-reviews-for-pull-requests/">enforcing code reviews
for PR's</a>, at least for the default branch.</li>
</ul>
</li>
<li>In <code>https://github.com/w3c/<REPO>/settings/installations</code>, under <em>Services</em>, you may want to add a handy
<strong>service</strong>; like an IRC notifier, or a Twitter bridge (depending on the nature of your repository, of course).</li>
</ul>
</section>
<section id="fields">
<h4>Fill in common fields <a href="#fields">🔗</a></h4>
<p>In particular, the three fields that appear at the top of the main page of the repo: <strong>description</strong> (something short),
<strong>website</strong> (often pointing to GitHub Pages) and <strong>topics</strong> (tags).</p>
<p>Check out how those are set up <a href="https://github.com/w3c/echidna">in Echidna</a>, for example.</p>
</section>
</section>
<section id="metadata">
<h3>Include sufficient metadata <a href="#metadata">🔗</a></h3>
<section id="git">
<h4>Git special files <a href="#git">🔗</a></h4>
<p>Have a <a href="https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring"><code>.gitignore</code></a>
(hidden file) in the root directory of your repo to list files and directories that you do <em>not</em> want to keep under version
control.
Typically something along the lines of:</p>
<pre>node_modules/
npm-debug.log
logs/</pre>
<p>See <a href="https://github.com/w3c/validate-repos/blob/main/.gitignore">an example</a>.</p>
<p>Ideally, <strong>this file should <em>not</em> contain filenames or patterns that are associated to specific OS's, IDE's or
editors</strong>; eg <code>.DS_Store</code> (MacOS), <code>Thumbs.db</code> (Windows), <code>*~</code> (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 <em>locally</em>, like
<a href="https://git-scm.com/docs/git-config#Documentation/git-config.txt-coreexcludesFile">configuring your Git to do so</a>.</p>
</section>
<section id="boilerplate">
<h4>GitHub boilerplate files <a href="#boilerplate">🔗</a></h4>
<p>To keep the root directory of the repository clean and manageable, store as many metadata files under <code>.github/</code> as
possible.
You should certainly have a <a href="https://help.github.com/articles/about-readmes/"><code>README.md</code></a> there.</p>
<p>Other useful files you may want to keep under that directory are these (in decreasing order of importance):</p>
<ul>
<li><a href="https://help.github.com/articles/setting-guidelines-for-repository-contributors/"><code>CONTRIBUTING.md</code></a></li>
<li><a href="https://help.github.com/articles/about-issue-and-pull-request-templates/"><code>ISSUE_TEMPLATE.md</code> and
<code>PULL_REQUEST_TEMPLATE.md</code></a></li>
<li><a href="https://help.github.com/articles/about-codeowners/"><code>CODEOWNERS</code></a></li>
<li><a href="https://help.github.com/articles/adding-a-code-of-conduct-to-your-project/"><code>CODE_OF_CONDUCT.md</code></a></li>
</ul>
<p>An exception to this rule is the file
<a href="https://help.github.com/articles/adding-a-license-to-a-repository/"><code>LICENSE.md</code></a>,
which should be in the root directory of the project,
<a href="https://github.com/benbalter/licensee/issues/250#issuecomment-353985847">or else GitHub will not find it</a>.</p>
<p>See <a href="https://github.com/w3c/validate-repos/blob/main/LICENSE.md">an example</a>.</p>
</section>
<section id="w3c">
<h4>W3C-specific metadata <a href="#w3c">🔗</a></h4>
<p>Usually applicable only to repositories containing specs (<em>not</em> software).</p>
<p>See <a href="w3c.json.html">the <code>w3c.json</code> file</a>.</p>
</section>
</section>
<section id="perms">
<h3>Handle permissions well <a href="#perms">🔗</a></h3>
<p>Make sure you list the right <em>teams</em> and <em>individuals</em> under “Collaborators & teams”:</p>
<pre>https://github.com/w3c/<REPO>/settings/collaboration</pre>
<p>In particular, be conservative about assigning editing (write) permissions and do so only for known collaborators.</p>
</section>
<section id="vulns">
<h3>Make sure you receive vulnerability alerts <a href="#vulns">🔗</a></h3>
<p>Usually applicable only to repositories containing software (<em>not</em> specs), and assuming the language/platform detected in the
repository is understood and supported by GitHub; find out
<a href="https://help.github.com/articles/about-security-alerts-for-vulnerable-dependencies/">in their help pages</a>.</p>
<p>Enable vulnerability alerts in settings, here:</p>
<pre>https://github.com/w3c/<REPO>/settings#vulnerability-alerts-feature</pre>
<p>Once enabled, vulnerabilities will be shown highlighted in two places:</p>
<ul>
<li>At the top of the main page of the repo; ie <code>https://github.com/w3c/<REPO></code></li>
<li>On the <em>Dependency Graph</em> page; ie <code>https://github.com/w3c/<REPO>/network/dependencies</code></li>
</ul>
<p>Finally, make sure you are receiving <em>notifications</em> about vulnerability alerts:
<a href="https://github.com/settings/notifications"><code>github.com/settings/notifications</code></a> (bottom of the page).</p>
</section>
<section id="ci">
<h3>Set up <abbr title="continuous integration">CI</abbr> <a href="#ci">🔗</a></h3>
<p><a href="https://travis-ci.com/">Travis CI</a> is our recommended tool to do CI; check out
<a href="https://travis-ci.org/w3c/">our repos there</a>.</p>
<p>A particular example of Travis configuration (see links below for more information):</p>
<pre>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}"</pre>
<p>Travis CI help pages referenced above:</p>
<ul>
<li><a href="https://docs.travis-ci.com/user/languages/javascript-with-nodejs/">Building a JavaScript and Node.js project</a></li>
<li><a href="https://docs.travis-ci.com/user/build-stages/">Build Stages</a></li>
<li><a href="https://docs.travis-ci.com/user/notifications/">Configuring Build Notifications</a></li>
</ul>
<p>See <a href="https://travis-ci.org/w3c/echidna">an example of Travis report page</a>.</p>
<p>The specifics of Travis configuration depend greatly on the language/platform and on the dependencies and tools involved.
See <a href="https://docs.travis-ci.com/">the documentation</a> or browse existing repositories using Travis to learn more.</p>
</section>
<section id="repository-manager">
<h3>Set up Repository Manager <a href="#repository-manager">🔗</a></h3>
<p>(Applicable only to repositories containing specs, <em>not</em> software.)</p>
<p>You may want to add your new repository containing a spec in
the <a href="https://labs.w3.org/repo-manager/">W3C Repository Manager</a>.
This is a tool that helps with IPR managements from public contributors; check with the Systeam if in doubt.</p>
</section>
<section id="branches2">
<h3>Patrol branches often <a href="#branches2">🔗</a></h3>
<p>See also <a href="#branches">Delete your branches soon</a>.</p>
<p>From time to time, check the list of all branches in the project, <code>https://github.com/w3c/<REPO>/branches/all</code>, and
delete the ones that aren't being used; branches that are <em>not</em> ahead of the default branch, and branches associated to PRs that
are either <em>merged</em> or <em>closed</em> already, are definitely good candidates for removal.
If in doubt, ask the author of the branch.</p>
</section>
<section id="tools">
<h3>Assess the quality of your repo <a href="#tools">🔗</a></h3>
<p>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:</p>
<ul>
<li><a href="https://github.com/w3c/validate-repos"><code>validate-repos</code></a>:
a W3C tool, specific for repos containing specs (<em>not</em> software); see
<a href="https://w3c.github.io/validate-repos/report.html">the kind of report it produces</a></li>
<li><a href="https://github.com/basicallydan/forkability/"><code>forkability</code></a>: an external project, useful for any kind of
public repository with open source</li>
</ul>
</section>
</section>
<section id="also">
<h2>See also <a href="#also">🔗</a></h2>
<ul>
<li>GitHub:
<ul>
<li>datree: <a href="https://www.datree.io/resources/github-best-practices">“Top 10 GitHub Best Practices”</a></li>
<li>Web Platform Tests:
<a href="https://web-platform-tests.org/writing-tests/github-intro.html">“Introduction to GitHub”</a></li>
<li>i18n activity:
<a href="https://w3c.github.io/i18n-activity/guidelines/github">“Github guidelines for working with i18n documents”</a></li>
</ul>
</li>
<li>Git: <a href="git.html">Git recipes & tricks</a></li>
<li>Node.js: <a href="https://github.com/w3c/nodejs">best practices, recommended tools and template projects</a> (public repo).</li>
</ul>
</section>
</main>
<footer>
<address><a href="https://github.com/w3c/w3c.github.io/">We are on GitHub</a></address>
<p><a href="https://www.w3.org/"><img src="img/w3c.svg" width="65" height="45" alt="W3C Logo"></a></p>
</footer>
</body>
</html>