-
Notifications
You must be signed in to change notification settings - Fork 40
/
Copy pathworkflow.html
157 lines (156 loc) · 6.9 KB
/
workflow.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
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width">
<title>Workflow for editors and other contributors</title>
<link rel="stylesheet" href="css/wgio.css">
<link rel="icon" type="image/x-icon" href="//labs.w3.org/favicon.ico">
</head>
<body>
<header>
<h1>Workflow for editors and other contributors</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>
<main>
<p>
A good practice for GitHub is to use <a href="https://help.github.com/articles/about-pull-requests/">pull requests</a>.
It lets you propose changes to others without making changes to the <code>main</code> branch of the repository.
Once a pull request is opened, you can discuss and review the potential changes with
others and add follow-up commits before the changes are merged into the repository.
</p>
<ol>
<li>
<p>
Navigate to the repo.
</p>
<pre>cd specs-on-github</pre>
</li>
<li>
<p>
Checkout the main branch of your repository (in general, this is the <code>main</code> branch).
</p>
<pre>git checkout main</pre>
</li>
<li>
<p>
Make sure the main branch is up-to-date with upstream.
</p>
<pre>git pull</pre>
<p>
If you forked the repository on GitHub, you may need to indicate the upstream repository more explicitly.
</p>
</li>
<li>
<p>
Create a new branch for your upcoming pull request (one branch per pull request). Please make branch names
informative - by including the issue or bug number for example.
</p>
<pre>git checkout -b my-wonderful-edits-for-87</pre>
</li>
<li>
<p>
Make your edits in your favorite editor.
</p>
</li>
<li>
<p>
Add your edits to prepare your commit by <a href="https://git-scm.com/book/en/v2/Git-Tools-Interactive-Staging">staging</a> them.
This will help you to easily craft your commits to include only certain combinations and parts of files.
Best is to use the interactive patch mode (new files still need to be added explicitly), where you can select which change should
be part of the commit. This allows you to make multiple edits at once and split them into different more
meaningful/easy-to-review commits.
</p>
<pre>git add -p</pre>
</li>
<li>
<p>
Commit your staged edits. If you're fixing an issue, reference it in the commit e.g. <code>fix #87</code>
(if you write close or fix, it will automatically close the issue once the commit is added to the main branch).
</p>
<pre>git commit -m "<purpose of your edits> (fix #number)"</pre>
<p>This command allows you to replace the last commit with a new one, if you feel the need to change it:</p>
<pre>git commit --amend</pre>
</li>
<li>
<p>
Once all your commits are done, push your branch upstream.
</p>
<pre>git push --set-upstream origin my-wonderful-edits-for-87</pre>
</li>
<li>
<p>
Using your favorite browser, navigate to the repo on GitHub, e.g.
</p>
<pre>https://github.com/tobie/specs-on-github/</pre>
</li>
<li>
<p>
Once your authenticated on the repo page, a new button should appear on the page to create a new
pull request (<code>Compare & pull request</code>). Go ahead and punch it.
</p>
<p><img src="img/create-a-pr.png" alt="Compare & pull request" /></p>
</li>
<li>
<p>
Make sure you like the title of your pull request, add a proper description (including mentioning the contributors with
<a href="https://github.com/w3c/licenses/blob/main/SW-CONTRIBUTING.md">"+@username"</a>), and use
<a href="issue-metadata.html">proper GitHub labels</a>, add one or more reviewers so they get pinged.
Once you're satisfied, create the pull request. Note that you can update all of that information
after that if needed.
</p>
</li>
<li>
<p>
All normative spec changes are generally expected to have a corresponding pull request in
<a href="https://github.com/w3c/web-platform-tests/">web-platforms-tests</a>,
either in the form of new tests or modifications to existing tests, or must include the rationale for why test
updates are not required for the proposed update.
</p>
<p>
Typically, both pull requests (spec updates and tests) will be merged at the same time. If a pull request
for the specification is approved but the other needs more work, add the
'<a href="https://w3c.github.io/issue-metadata.html">needs tests</a>' label or,
in web-platform-tests, the
'<a href="https://github.com/w3c/web-platform-tests/issues?utf8=%E2%9C%93&q=label%3Astatus%3Aneeds-spec-decision%20">status:needs-spec-decision</a>'
label. Note that a test change that contradicts
the specification should not be merged before the corresponding specification change.
</p>
<p>
If testing is not practical due to <a href="https://github.com/w3c/web-platform-tests/">web-platforms-tests</a> limitations,
please explain why and if appropriate file an issue with the
'<a href="https://github.com/w3c/web-platform-tests/issues?utf8=%E2%9C%93&q=label%3Atype%3Auntestable%20">type:untestable</a>'
label to follow up later. For tests that aren't ready for the specification, you may use the <a
href="http://web-platform-tests.org/writing-tests/file-names.html#test-features"><code>.tentative</code> filename convention</a>.
</p>
</li>
<li>
<p>
Wait for the needed reviews. All pull requests must have been reviewed by one or more participants of the working group.
They can use approve changes, give you <code>+1</code>, comment, etc. You may need to make additional commits in your branch and push them
again in order to address the review. The pull request will keep tracking the branch so it will get automatically updated with the new commits.
</p>
</li>
<li>
<p>
Once the pull request gets enough support, it can be merged (you should use the <code>Squash and merge</code> to avoid cluttering the
commit history and consider cleaning up the commit message). Delete your ad-hoc branch <code>my-wonderful-edits-for-87</code>. You're done.
</p>
</li>
</ol>
<p>(For help and tips about Git itself, refer to <a href="git.html">the dedicated page</a>.)</p>
</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>