-
Notifications
You must be signed in to change notification settings - Fork 11
/
index.html
205 lines (200 loc) · 10.6 KB
/
index.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
<html>
<head>
<title>GitGitGadget - contributing git.git patches via GitHub PRs</title>
<style>
body {
font-family: sans-serif;
background-color: #d7cdc0ff;
background-image: linear-gradient(#d7cdc0ff, #fdf7f6ff);
margin-right: 10%;
margin-left: 10%;
}
.block {
background-color: rgb(247, 243, 239);
color: #000000;
padding: 1em;
padding-top: .1em;
padding-bottom: .1em;
border-radius: 2em;
}
.banner {
text-align: center;
font-weight: bold;
}
big {
font-size: 400%;
}
small {
font-size: 70%;
}
.tg {
border-collapse: collapse;
border-spacing: 0;
margin: 0px auto;
}
.tg td {
padding: 10px 5px;
border-style: solid;
border-width: 1px;
overflow: hidden;
word-break: normal;
border-color: black;
}
.tg th {
font-weight: bold;
padding: 10px 5px;
border-style: solid;
border-width: 1px;
overflow: hidden;
word-break: normal;
border-color: black;
}
.tg .tg-baqh {
width: 15%;
text-align: center;
vertical-align: center;
}
.tg .tg-0lax {
width: 70%;
text-align: left;
vertical-align: center;
}
@media screen and (max-width: 767px) {
.tg {
width: auto !important;
}
.tg col {
width: auto !important;
}
.tg-wrap {
overflow-x: auto;
-webkit-overflow-scrolling: touch;
margin: auto 0px;
}
}
</style>
</head>
<body>
<div class="banner">
<img src="images/gitgitgadget-explanation.png" alt="An arrow from git logo to an envelop with git logo. The arrow is labelled by famous Inspector Gadget hat."/>
<big>GitGitGadget</big><br />
Contributing git.git patches via GitHub PRs<br />
<small>... one iteration at a time... </small>
</div><hr />
<div class="block">
<p>
Unlike most open source projects, Git itself does not accept code contributions via Pull Requests.
Instead, patches are <a href="https://git-scm.com/docs/SubmittingPatches">submitted to the Git mailing list</a> for review and will be applied manually by the Git maintainer.
</p><p>
Apart from lacking the convenience of a web interface, this process also puts considerable demands on the code contributions: the mails are expected to be plain text only (no HTML!), for example, and the diffs embedded in the mails must apply cleanly (no whitespace changes!), among other things.
</p><p>
A few tutorials out there try to help with this process (e.g. <a href="https://github.com/git-for-windows/git/blob/master/CONTRIBUTING.md">Git for Windows' detailed instructions how to contribute patches to the Git project</a>, or Git's <a href="https://git-scm.com/docs/MyFirstContribution">MyFirstContribution tutorial</a>).
GitGitGadget tries a different approach: allow contributing patches to the Git project itself by opening a Pull Request either at <a href="https://github.com/gitgitgadget/git">https://github.com/gitgitgadget/git</a> or directly at <a href="https://github.com/git/git">https://github.com/git/git</a> and let GitGitGadget prepare and send the corresponding mails.
</p>
</div>
<h2 id="how-can-you-use-gitgitgadget">How can you use GitGitGadget? <a href="#how-can-you-use-gitgitgadget">#</a></h2>
<div class="block">
<p>
So you cloned <a href="https://github.com/git/git">https://github.com/git/git</a> and implemented a bug fix or a new feature?
And you already pushed it to your own fork?
Good, now is the time to direct your web browser to <a href="https://github.com/gitgitgadget/git">https://github.com/gitgitgadget/git</a> (or to <a href="https://github.com/git/git">https://github.com/git/git</a> ) and to open a Pull Request.
A few things to note about a GitGitGadget Pull Request:
<ul>
<li>Please make sure to use a descriptive title and description; GitGitGadget will use these as the subject and body of the cover letter (check out the <a href="https://git-scm.com/docs/MyFirstContribution#cover-letter">MyFirstContribution</a> tutorial if you are not familiar with this terminology).</li>
<li>If your pull request consist of a single commit, leave the pull request description empty, as your commit message itself should be enough to explain the rationale for your changes.</li>
<li>You can CC potential reviewers by adding a footer to the PR description with the following syntax:<br />
<code>CC: Revi Ewer <[email protected]>, Ill Takalook <[email protected]></code>
</li>
</ul>
</p><p>
You will also want to read <a href="https://git-scm.com/docs/SubmittingPatches">Git's contribution guidelines</a> to make sure that your contributions are in the expected form, as well as the project's <a href="https://github.com/git/git/blob/master/Documentation/CodingGuidelines">coding guidelines</a>.
You might also want to read the <a href="https://git-scm.com/docs/gitworkflows">gitworkflows</a> manual page to understand how your contributions will be integrated in Git's repository, as well as <a href="https://github.com/git/git/blob/todo/MaintNotes">this note from Git's maintainer</a>.
</p><p>
The first time you use GitGitGadget, you need to be added to the list of users with permission to use GitGitGadget (this is a <i>very</i> simple anti-spam measure).
Using <a src="https://web.libera.chat/#git-devel">IRC</a> or <a src="https://github.com/gitgitgadget/git/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+%22%2Fallow%22">PRs</a> you can find a user already on this list and request them to add you to the list.
To do so, they simply have to add a comment to that Pull Request that says <code>/allow</name></code>.
</p><p>
The Pull Request will trigger a few Checks, most importantly one that will build Git and run the test suite on the main platforms, to make sure that everything works as advertised.
</p><p>
Once you feel everything is ready to go, add a comment to that Pull Request saying <code>/preview</code>. This will send you a copy of the Pull Request to check.
Once you are happy with the result, add a comment to that Pull Request saying <code>/submit</code>.
This will trigger GitGitGadget (you can see the progress via the Check called "GitGitGadget PR Handler"): it will wrap your Pull Request into a nice bundle of mails in the format expected on the Git mailing list.
</p>
</div>
<h2 id="what-happens-after-gitgitgadget-sent-the-mails">What happens after GitGitGadget sent the mails? <a href="#what-happens-after-gitgitgadget-sent-the-mails">#</a></h2>
<div class="block">
<p>
The patches will be reviewed by volunteers (be gentle...) and you will most likely receive helpful comments.
The Git developer community is globally distributed, so please wait a day or two for reviewer comments to trickle in before sending another iteration of your patch series (if needed).
</p><p>
In the case that a reviewer asks for changes, you should respond either acknowledging that you will make those changes or making an argument against the requested changes.
If your patches need to be revised, please use <code>git rebase -i</code> to do that, then force-push, then update the description of the Pull Request by adding a summary of the changes you made, and then issue another <code>/submit</code>.
</p>
</div>
<h2 id="should-i-use-gitgitgadget-on-gitgitgadgets-git-fork-or-on-gits-github-mirror">Should I use GitGitGadget on GitGitGadget's Git fork or on Git's GitHub mirror? <a href="#should-i-use-gitgitgadget-on-gitgitgadgets-git-fork-or-on-gits-github-mirror">#</a></h2>
<div class="block">
<p>
GitGitGadget works on both GitGitGadget's Git fork (<a href="https://github.com/gitgitgadget/git">https://github.com/gitgitgadget/git</a>) and Git's GitHub mirror (<a href="https://github.com/git/git">https://github.com/git/git</a>).
However, some functionality is only available when opening a PR on GitGitGadget's Git fork.
</p>
<div class="tg-wrap"><table class="tg">
<tr>
<th class="tg-0lax">Features</th>
<th class="tg-baqh"><a href="https://github.com/gitgitgadget/git">gitgitgadget/git</a></th>
<th class="tg-baqh"><a href="https://github.com/git/git">git/git</a></th>
</tr>
<tr>
<td class="tg-0lax">Mirrors emails answers as PR comments</td>
<td class="tg-baqh">✓</td>
<td class="tg-baqh">✓</td>
</tr>
<tr>
<td class="tg-0lax">Mirrors PR comments as emails to the list</td>
<td class="tg-baqh">✗</td>
<td class="tg-baqh">✗</td>
</tr>
<tr>
<td class="tg-0lax">Builds Git and runs the test suite on Linux, macOS, Windows and FreeBSD</td>
<td class="tg-baqh">✓</td>
<td class="tg-baqh">✓</td>
</tr>
<tr>
<td class="tg-0lax">Comments on the PR when a topic branch is created in the <a href="https://github.com/gitster/git/branches">maintainer's fork</a></td>
<td class="tg-baqh">✓</td>
<td class="tg-baqh">✓</td>
</tr>
<tr>
<td class="tg-0lax">Comments on the PR when the series is integrated into <code>seen</code>, <code>next</code>, <code>master</code> and <code>maint</code></td>
<td class="tg-baqh">✓</td>
<td class="tg-baqh">✓</td>
</tr>
<tr>
<td class="tg-0lax">Adds a label to the PR when the series is integrated into <code>seen</code>, <code>next</code>, <code>master</code> and <code>maint</code></td>
<td class="tg-baqh">✓</td>
<td class="tg-baqh">✓</td>
</tr>
<tr>
<td class="tg-0lax">PRs can target <code>seen</code>, <code>next</code>, <code>master</code> and <code>maint</code></td>
<td class="tg-baqh">✓</td>
<td class="tg-baqh">✓</td>
</tr>
<tr>
<td class="tg-0lax">PRs can target any topic branch in the maintainer's fork, as well as <a href="https://github.com/prati0100/git-gui"><code>git-gui/master</code></a></td>
<td class="tg-baqh">✓</td>
<td class="tg-baqh">✗</td>
</tr>
<tr>
<td class="tg-0lax">Creates a direct link between the last commit of the series and the corresponding commit in the "most upstream" integration branch as a GitHub check</td>
<td class="tg-baqh">✓</td>
<td class="tg-baqh">✗</td>
</tr>
</table></div>
</div>
<h2 id="but-what-is-gitgitgadget">But... what <i>is</i> GitGitGadget? <a href="#but-what-is-gitgitgadget">#</a></h2>
<div class="block">
<p>
GitGitGadget itself is a GitHub App that is backed by an Azure Function written in pure Javascript which in turn triggers an Azure Pipeline written in Typescript (which is really easy to understand and write for everybody who knows even just a little Javascript), maintained at <a href="https://github.com/gitgitgadget/gitgitgadget">https://github.com/gitgitgadget/gitgitgadget</a>.
</p>
</div>
</body>
</html>