forked from w3c/w3c.github.io
-
Notifications
You must be signed in to change notification settings - Fork 0
/
repo-management.html
195 lines (190 loc) · 8.99 KB
/
repo-management.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
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width">
<title>Contributor Management</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>Contributor Management</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>
This document covers a tool that was created to support contributions made to a group, under the
form of pull requests, in order to assess whether they are IPR-OK or not.
</p>
<p>
The tool is at:
<a href="https://labs.w3.org/repo-manager/">https://labs.w3.org/repo-manager/</a>.
</p>
<p>
A number of operations in the tool require logging in through GitHub as the related actions you can undertake through the tool (or that the tool can
undertake on your behalf when reacting to a GitHub event) require authorized access to GitHub.
</p>
<p>
There are several tools of use:
</p>
<section>
<h3>New Repository <span class=acl>login required</span></h3>
<p>
This is basically what people should use when they want to start a new specification in a CG or a WG. It gives you a choice of the organisations under which you are allowed to create a new
repo (including your own user), and you can pick the name of the repo and the group(s) to
which it belongs.
</p>
<p>
Hitting "Create" can take a little while as the tool does all of the following, live:
</p>
<ul>
<li>
Creates the repo on GitHub
</li>
<li>
Adds several files, notably the <code>LICENSE</code> and <code>CONTRIBUTE.md</code>, a
<code>w3c.json</code> file which can be used by other tools, and an <code>index.html</code>
that's a bare-bones ReSpec spec ready to be edited.
</li>
<li>
Adds a hook to the repo such that pull requests and comments on them are sent to us,
including one distinct cryptographic secret per repo.
</li>
<li>
Saves all the relevant info on our side.
</li>
</ul>
<p>
Most users should only ever have to use that. Once done they can go and play in their repo.
</p>
</section>
<section>
<h3>Import Repository <span class=acl>login required</span></h3>
<p>
This is the same as "New" but for an existing repo. It will *never* overwrite something there
so it is the user's responsibility to check that the repo is okay.
</p>
</section>
<section>
<h3>How Pull Requests Get Handled</h3>
<p>
Whenever a pull request is made against a repo that is under the tool's management,the tool gets
notified. It uses this information to assess if the PR is acceptable (i.e. all its
contributors have made the relevant IPR commitment).
</p>
<p>
Count as contributors not just the person making the pull request, but also anyone added
either in the PR description or in any subsequent comment using "+@username" on a line on its
own. If a contributor was added by mistake, she can be removed wit "-@username" on a line on
its own.
</p>
<p>
Every time a PR is created or has a comment with a username change, the status of the PR is
changed. If it's okay it'll get changed to green with a note indicating that it's fine; if not
it gets changed to some ugly brown with a red cross (and a link that people can use to check
the issue in more detail).
</p>
<p>On the page that explains the IPR failure, one can mark a given Pull Request as non-substantive: this will post a comment on the pull request under the name of the user, and will clear the flag for the said pull request.</p>
<p>When a pull request gets flagged as not OK by the tool, it will attempt to notify the github users listed in the <a href="w3c.json.html#contacts"><code>contacts</code></a> property of the <code>w3c.json</code> file in the repo.</p>
<p>When it gets flagged as not OK because the contributor could not be automatically associated with a W3C profile, the contributor will also be notified to ask them to <a href="https://www.w3.org/users/myprofile/connectedaccounts">connect their W3C & GitHub accounts</a>.</p<
</section>
<hr>
<section>
<h3>Currently Open Pull Requests</h3>
<p>
This list all PRs that are now open, even old ones. It lists useful details such as which
users are being problematic either because they are unknown (not in the system at all) or
outside (known to the system but not in one of the right groups for that repo).
</p>
<p>
You can go to PR details by clicking "Details".
</p>
</section>
<section>
<h3>PR Details</h3>
<p>
If the PR is not in an acceptable state, this will list problematic users with possible options to fix
each of them, and a button to "Mark the PR as non-substantive".</p>
<p>
The vast majority of non-acceptable PRs for a newly added repo will come from people whose W3C profile is not known (and thus neither are their affiliation and associated IPR commitments).
</p>
<p>
When all problematic users have had their W3C profile associated, return to the PR details page and hit
"Revalidate". We hope in the future to <a href="https://github.com/w3c/ash-nazg/issues/26">revalidate every time a user is added or edited</a>. Revalidation will of course update both the local
state and the PR's mergability indicator on GitHub.
</p>
</section>
<section>
<h3>Active Last Week PRs</h3>
<p>
This is a list of pull requests, in any state, that saw activity last week. They can be
filtered according to the affiliation of the companies that made the contributions. This is
essentially so that AC reps who have people in CGs who are only supposed to contribute to some
specific work but not all of it can monitor what's been going on and avail themselves of their
45 days retraction window. Similar affordances are available as for the list of open PRs.
</p>
</section>
<section>
<h3>Edit User <span class=acl>login required</span></h3>
<p>In most cases, this interface will not be needed - it is only useful for cases where it is not possible or practical for a GitHub user to <a href="https://www.w3.org/users/myprofile/connectedaccounts">associate their GitHub account with their W3C account</a>.</p>
<p>
The interface to edit users is where the W3C data model and the GitHub data model get to meet.
This alone is scary; I've tried to make it less scary.
</p>
<p>
A list of the groups known to the system is show, the user can be added and removed from them
there. If the user's affiliation is unset, once some groups have been added you can click
"Set". This will load up a list that is the *intersection* of membership in the selected
groups. The UI will also try to select the user with the name matching their GitHub profile
(which may not always work, but often does). Hitting "OK" will associate the GH user with the
W3C user, making it possible for us to use affiliation information. Don't forget to hit
"Save".
</p>
</section>
<section>
<h3>Admin > Users <span class=acl>admin required</span></h3>
<p>
This is a list of users. Things you can do there include making them admins and giving them
blanket contribution rights. <strong>USE EITHER WITH CARE</strong>.
</p>
<p>
Admins should normally not be able to break the system, but they can enter all sorts of bogus
information that would be really annoying. Only grant admin when you're sure; it's probably
better to ask others first.
</p>
<p>
Blanket is a different type of superpower: users with blanket access are considered acceptable
contributors to ALL repos, irrespective of their group memberships. This should normally be
restricted to W3C team people.
</p>
</section>
<section>
<h3>Admin > Groups <span class=acl>admin required</span></h3>
<p>
This is a list of all W3C groups. You will note that most have an "Add" button next to them:
those are the ones that are in W3C but not in this system. Please do *not* start adding groups
unless they explicitly want to be managed under this system. We only want people to
create/import repos for groups that are actually using this system. Clicking "Add" makes that
group one of those available for repos and users to belong to.
</p>
<p>
The source is at <a
href="https://github.com/w3c/ash-nazg">https://github.com/w3c/ash-nazg</a>.
</p>
</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>