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
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
|
<?xml version="1.0"?>
<guide self="ebuild-maintenance/git/">
<chapter>
<title>Git for Gentoo Developers</title>
<body>
<p>
This guide covers git usage instructions and policies specific to Gentoo ebuild
development. It assumes that the readers possess basic git knowledge.
For a generic guide, please see the official
<uri link="https://git-scm.com/book/">git book</uri>.
</p>
</body>
<section>
<title>Preparing a development checkout</title>
<subsection>
<title>Cloning the gentoo.git repository</title>
<body>
<p>
The ebuild development happens on the official git repository. You can push
your changes only through the SSH protocol. Therefore, clone the repository
using:
</p>
<pre>
git clone git@git.gentoo.org:repo/gentoo.git
</pre>
<p>
If you do not have SSH access to the Gentoo git service, you can use the anongit
mirror for read-only access instead:
</p>
<pre>
git clone https://anongit.gentoo.org/git/repo/gentoo.git
</pre>
<p>
Normally git will fetch the complete history from the start of git repository
(Aug 2015). This can require a significant amount of disk space. If you do not
need the full history, you can use the <c>--depth</c> option to create a shallow
clone, including only a subset containing the the newest commits. For example,
<c>--depth=50</c> will include the 50 newest commits.
</p>
<p>
Please note that git version 1.9 or newer is required to push when using
a shallow clone.
</p>
</body>
</subsection>
<subsection>
<title>Configuration specific to the Gentoo repository</title>
<body>
<p>
To ensure that the Gentoo policies are followed, you should set the following
configuration variables:
</p>
<pre>
git config --local user.name "${YOUR_FULL_NAME}"
# use your @gentoo.org address even if you have a different default
git config --local user.email "${YOUR_NICKNAME}@gentoo.org"
# enable commit and push signing
git config --local user.signingkey "0x${LONG_OPENPGP_KEY_ID}"
git config --local commit.gpgsign 1
git config --local push.gpgsign 1
# prevent implicit merges on 'git pull'
git config --local pull.ff only
</pre>
</body>
</subsection>
<subsection>
<title>Grafting converted CVS history into the clone</title>
<body>
<p>
To include the converted CVS history in the git repository, you can
graft it into the repository:
</p>
<pre>
git remote add history https://anongit.gentoo.org/git/repo/gentoo/historical.git/
git fetch history
git replace --graft 56bd759df1d0c750a065b8c845e93d5dfa6b549d history/master
</pre>
<p>
Once this is done, git commands such as <c>git log</c> will include
the historical commits after the initial git commit.
</p>
</body>
</subsection>
</section>
<section>
<title>Committing to gentoo.git</title>
<subsection>
<title>Committing and verifying commits</title>
<body>
<p>
The recommended way of committing to the Gentoo repository is to use <c>repoman
commit</c>. It automatically performs the necessary QA checks on the package
being committed and has other features helping with the Gentoo workflow.
However, it is currently limited to creating a single commit to a single
package.
</p>
<p>
For any other use case, <c>git commit</c> and other git commands need to be
used. The valid uses of git include:
</p>
<ul>
<li>creating commits spanning multiple packages and/or multiple areas
of the Gentoo repository (eclasses, licenses, profiles…),</li>
<li>amending a commit created via <c>repoman commit</c> with additional files
or fixups,</li>
<li>combining multiple commits created via <c>repoman commit</c> using <c>git
rebase</c>.</li>
</ul>
<p>
Whenever repoman is not used to commit, you need to manually verify all
packages affected by the commit using <c>repoman full</c>. Since repoman
is not aware of staged changes, please make sure that all files are included
in the commit. Also when not using repoman, you must perform a manual sign-off
to the <uri link="https://www.gentoo.org/glep/glep-0076.html#certificate-of-origin">
Certificate of Origin</uri> using the <c>-s</c> or <c>--signoff</c> option
with your git commit commands. Make sure you have read and understand the
actual Certificate.
</p>
</body>
</subsection>
<subsection>
<title>Atomic commits</title>
<body>
<p>
Whenever possible, use atomic commits. Try to split your changes into logical
commits, abiding by the following three rules as much as possible:
</p>
<ol>
<li>
Do not include multiple irrelevant changes in a single commit. However, make
sure not to split relevant changes unnecessarily. For example, if a version bump
requires changes in the ebuild, it is correct to perform them in a single
commit. However, if you are fixing an additional bug that has been present
in the previous version, the fix belongs in a separate commit.
</li>
<li>
Split commits at logical unit boundaries. When updating multiple packages,
preferably use a single commit for each package. Avoid combining changes
to ebuilds, eclasses, licenses, profiles etc. in a single commit. However,
do not split relevant or interdependent changes within a single package.
</li>
<li>
Avoid creating commits introducing a temporary breakage. Unless impossible,
add packages in dependency install order. Add licenses before the packages
needing them. Commit <c>package.mask</c> and other profile changes before
ebuilds relying on them. Usually it is also acceptable to include those changes
along with the commit adding the package.
</li>
</ol>
<p>
Please note that revision bumps count as side effects of the changes requiring
them and do not belong in separate commits. When doing multiple irrelevant
changes that require a revision bump, it is only necessary to bump the revision
in the first commit in the series introduced by a single push.
</p>
</body>
</subsection>
<subsection>
<title>Git Commit Message Format</title>
<body>
<p>
It is important to format the commit messages properly so that they
communicate the changes to the reader in a clear and concise
way. Additionally, consistency in message format allows for easier
parsing by external tools. The first line of the commit message should
contain a brief summary of the changes, followed by an empty new
line. From the third line onward should be a detailed, multiline
explanation of the changes introduced by the commit. At the very end,
auxiliary information such as the bugs related to the commit,
contributors, and reviewers should be listed using RFC822/git style
tags. The sign-off agreement will be added there as well when applied
with the commit action. The length of the lines in the message should
be 70-75 characters at maximum.
</p>
<p>
The summary line should start with referencing what is affected by the
change followed by a colon ':' character. Use the rules in the
following list to determine the proper format based on what has
changed, substituting the package, category and eclass names
appropriately:
</p>
<ul>
<li><c>${CATEGORY}/${PN}:</c>Single Package (Note that <c>repoman commit</c>
automatically inserts this for you)</li>
<li><c>${CATEGORY}:</c> Package Category</li>
<li><c>profiles:</c> Profile Directory</li>
<li><c>${ECLASS}.eclass:</c> Eclass Directotry</li>
<li><c>licenses:</c> Licenses Directory</li>
<li><c>metadata:</c> Metadata Directory</li>
</ul>
<p>
For packages where <c>${CATEGORY}/${PN}:</c> is long, the line length
limit can be exceeded, if absolutely necessary, to ensure a more
useful summary line. If a commit affects multiple directories, prepend
the message with which reflects the intention of the change best. If
there are any bugs on Gentoo Bugzilla associated with the commit, the id
of the bug can be appended to the summary line using the format
<c>#nnnnnn</c>. If you are modifying keywords, clearly state what
keywords are added/removed.
</p>
<warning>
By default, lines starting with <c>#</c> are considered to be comments
by git and not included in the commit message. Make sure that a new
line does not start with <c>#nnnnnn</c>. Optionally, git can be
configured to use a different character for comments by changing the
<c>commentchar</c> option.
</warning>
<p>
For non-trivial commits, the message should contain a detailed
explanation of what the commit intends to change, why it is required,
and how it is accomplished, along with any other supplementary
information.
</p>
<p>
Finally the commit message should list auxiliary information such as
people who are involved in authoring, suggesting, reviewing and
testing the changes, and revelant bugs. Use RFC822/git style tags as
explained in the
<uri link="https://kernel.org/doc/html/latest/process/submitting-patches.html">
Linux Kernel patch guideline</uri>. Additionally, the following tags
are optionally used in Gentoo:
</p>
<ul>
<li><c>Bug:</c> Use this to reference bugs <e>without</e> closing them.
The value is a URL to the bug. If multiple bugs need to be referenced,
each one should be listed in a separate <c>Bug</c> tag. If a bug
on Gentoo Bugzilla, or an issue or a pull request on GitHub
is referenced, a reference to the commit will be added
automatically.</li>
<li><c>Closes:</c> Use this to reference bugs and close them
automatically. Alike <c>Bug:</c>, the value is a single URL to the bug,
and multiple tags can be used to close multiple bugs. If a bug on Gentoo
Bugzilla, or an issue or a pull request on a GitHub repository
mirrored by Gentoo is referenced, it will be closed (as fixed)
automatically with reference to the commit.</li>
<li><c>Package-Manager:</c> This is automatically inserted by
<c>repoman commit</c> and it specifies the version of
<c>sys-apps/portage</c> on the system.</li>
<li><c>RepoMan-Options:</c> This is automatically inserted by
<c>repoman commit</c> and records the options passed to repoman (such
as --force) for the commit.</li>
</ul>
<p>
When committing <uri link="::ebuild-writing/user-submitted">user
contributions</uri>, make sure to credit them in your commit message
with the user's full name and email address. Be aware and respectful
of their privacy: some users prefer to be only known by a
nickname. Take advantage of the tags such as <c>Suggested-By</c> or
<c>Reported-By:</c>when entering such information to the commit
message.
</p>
<p>
An example commit message is shown below:
</p>
<pre>
app-misc/foo: version bump to 0.5
This also adds a new USE flag 'bar' which controls the
new bar functionality introduced with this version.
Bug: https://bugs.gentoo.org/00000
Closes: https://bugs.gentoo.org/00001
Signed-off-by: Alice Bar <a.bar@example.org>
</pre>
</body>
</subsection>
</section>
</chapter>
</guide>
|
GitWeb