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
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
|
<!DOCTYPE html>
<html lang="en-US">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=Edge">
<link rel="stylesheet" href="/ostree/assets/css/just-the-docs-default.css">
<script src="/ostree/assets/js/vendor/lunr.min.js"></script>
<script src="/ostree/assets/js/just-the-docs.js"></script>
<meta name="viewport" content="width=device-width, initial-scale=1">
<!-- Begin Jekyll SEO tag v2.8.0 -->
<title>Contributing | ostreedev/ostree</title>
<meta name="generator" content="Jekyll v3.9.3" />
<meta property="og:title" content="Contributing" />
<meta property="og:locale" content="en_US" />
<meta name="description" content="ostree documentation" />
<meta property="og:description" content="ostree documentation" />
<link rel="canonical" href="https://ostreedev.github.io/ostree/CONTRIBUTING/" />
<meta property="og:url" content="https://ostreedev.github.io/ostree/CONTRIBUTING/" />
<meta property="og:site_name" content="ostreedev/ostree" />
<meta property="og:type" content="website" />
<meta name="twitter:card" content="summary" />
<meta property="twitter:title" content="Contributing" />
<script type="application/ld+json">
{"@context":"https://schema.org","@type":"WebPage","description":"ostree documentation","headline":"Contributing","url":"https://ostreedev.github.io/ostree/CONTRIBUTING/"}</script>
<!-- End Jekyll SEO tag -->
</head>
<body>
<a class="skip-to-main" href="#main-content">Skip to main content</a>
<svg xmlns="http://www.w3.org/2000/svg" class="d-none">
<symbol id="svg-link" viewBox="0 0 24 24">
<title>Link</title>
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-link">
<path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path>
</svg>
</symbol>
<symbol id="svg-menu" viewBox="0 0 24 24">
<title>Menu</title>
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-menu">
<line x1="3" y1="12" x2="21" y2="12"></line><line x1="3" y1="6" x2="21" y2="6"></line><line x1="3" y1="18" x2="21" y2="18"></line>
</svg>
</symbol>
<symbol id="svg-arrow-right" viewBox="0 0 24 24">
<title>Expand</title>
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-chevron-right">
<polyline points="9 18 15 12 9 6"></polyline>
</svg>
</symbol>
<!-- Feather. MIT License: https://github.com/feathericons/feather/blob/master/LICENSE -->
<symbol id="svg-external-link" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-external-link">
<title id="svg-external-link-title">(external link)</title>
<path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"></path><polyline points="15 3 21 3 21 9"></polyline><line x1="10" y1="14" x2="21" y2="3"></line>
</symbol>
<symbol id="svg-doc" viewBox="0 0 24 24">
<title>Document</title>
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-file">
<path d="M13 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9z"></path><polyline points="13 2 13 9 20 9"></polyline>
</svg>
</symbol>
<symbol id="svg-search" viewBox="0 0 24 24">
<title>Search</title>
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-search">
<circle cx="11" cy="11" r="8"></circle><line x1="21" y1="21" x2="16.65" y2="16.65"></line>
</svg>
</symbol>
<!-- Bootstrap Icons. MIT License: https://github.com/twbs/icons/blob/main/LICENSE.md -->
<symbol id="svg-copy" viewBox="0 0 16 16">
<title>Copy</title>
<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-clipboard" viewBox="0 0 16 16">
<path d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1h1a1 1 0 0 1 1 1V14a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V3.5a1 1 0 0 1 1-1h1v-1z"/>
<path d="M9.5 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3zm-3-1A1.5 1.5 0 0 0 5 1.5v1A1.5 1.5 0 0 0 6.5 4h3A1.5 1.5 0 0 0 11 2.5v-1A1.5 1.5 0 0 0 9.5 0h-3z"/>
</svg>
</symbol>
<symbol id="svg-copied" viewBox="0 0 16 16">
<title>Copied</title>
<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-clipboard-check-fill" viewBox="0 0 16 16">
<path d="M6.5 0A1.5 1.5 0 0 0 5 1.5v1A1.5 1.5 0 0 0 6.5 4h3A1.5 1.5 0 0 0 11 2.5v-1A1.5 1.5 0 0 0 9.5 0h-3Zm3 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3Z"/>
<path d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1A2.5 2.5 0 0 1 9.5 5h-3A2.5 2.5 0 0 1 4 2.5v-1Zm6.854 7.354-3 3a.5.5 0 0 1-.708 0l-1.5-1.5a.5.5 0 0 1 .708-.708L7.5 10.793l2.646-2.647a.5.5 0 0 1 .708.708Z"/>
</svg>
</symbol>
</svg>
<div class="side-bar">
<div class="site-header">
<a href="/ostree/" class="site-title lh-tight">
ostreedev/ostree
</a>
<a href="#" id="menu-button" class="site-button">
<svg viewBox="0 0 24 24" class="icon"><use xlink:href="#svg-menu"></use></svg>
</a>
</div>
<nav aria-label="Main" id="site-nav" class="site-nav">
<ul class="nav-list"><li class="nav-list-item"><a href="/ostree/" class="nav-list-link">libostree</a></li><li class="nav-list-item"><a href="/ostree/introduction/" class="nav-list-link">OSTree Overview</a></li><li class="nav-list-item"><a href="/ostree/repo/" class="nav-list-link">Anatomy of an OSTree repository</a></li><li class="nav-list-item"><a href="/ostree/deployment/" class="nav-list-link">Deployments</a></li><li class="nav-list-item"><a href="/ostree/atomic-upgrades/" class="nav-list-link">Atomic Upgrades</a></li><li class="nav-list-item"><a href="/ostree/adapting-existing/" class="nav-list-link">Adapting existing mainstream distributions</a></li><li class="nav-list-item"><a href="/ostree/formats/" class="nav-list-link">OSTree data formats</a></li><li class="nav-list-item"><a href="/ostree/buildsystem-and-repos/" class="nav-list-link">Writing a buildsystem and managing repositories</a></li><li class="nav-list-item"><a href="/ostree/repository-management/" class="nav-list-link">Managing content in OSTree repositories</a></li><li class="nav-list-item"><a href="/ostree/related-projects/" class="nav-list-link">Related Projects</a></li><li class="nav-list-item"><a href="/ostree/ima/" class="nav-list-link">Using Linux IMA with OSTree</a></li><li class="nav-list-item active"><a href="/ostree/CONTRIBUTING/" class="nav-list-link active">Contributing</a></li><li class="nav-list-item"><a href="/ostree/contributing-tutorial/" class="nav-list-link">OSTree Contributing Tutorial</a></li><li class="nav-list-item"><a href="/ostree/README-historical/" class="nav-list-link">Historical OSTree README</a></li></ul>
</nav>
<footer class="site-footer">
This site uses <a href="https://github.com/just-the-docs/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll.
</footer>
</div>
<div class="main" id="top">
<div id="main-header" class="main-header">
<div class="search">
<div class="search-input-wrap">
<input type="text" id="search-input" class="search-input" tabindex="0" placeholder="Search ostreedev/ostree" aria-label="Search ostreedev/ostree" autocomplete="off">
<label for="search-input" class="search-label"><svg viewBox="0 0 24 24" class="search-icon"><use xlink:href="#svg-search"></use></svg></label>
</div>
<div id="search-results" class="search-results"></div>
</div>
<nav aria-label="Auxiliary" class="aux-nav">
<ul class="aux-nav-list">
<li class="aux-nav-list-item">
<a href="https://github.com/ostreedev/ostree" class="site-button"
>
OSTree on GitHub
</a>
</li>
</ul>
</nav>
</div>
<div id="main-content-wrap" class="main-content-wrap">
<div id="main-content" class="main-content" role="main">
<h1 class="no_toc" id="contributing">
<a href="#contributing" class="anchor-heading" aria-labelledby="contributing"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Contributing
</h1>
<ol id="markdown-toc">
<li><a href="#submitting-patches" id="markdown-toc-submitting-patches">Submitting patches</a></li>
<li><a href="#commit-message-style" id="markdown-toc-commit-message-style">Commit message style</a></li>
<li><a href="#running-the-test-suite" id="markdown-toc-running-the-test-suite">Running the test suite</a></li>
<li><a href="#coding-style" id="markdown-toc-coding-style">Coding style</a></li>
<li><a href="#contributing-tutorial" id="markdown-toc-contributing-tutorial">Contributing Tutorial</a></li>
<li><a href="#release-process" id="markdown-toc-release-process">Release process</a></li>
</ol>
<h2 id="submitting-patches">
<a href="#submitting-patches" class="anchor-heading" aria-labelledby="submitting-patches"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Submitting patches
</h2>
<p>A majority of current maintainers prefer the GitHub pull request
model, and this motivated moving the primary git repository to
<a href="https://github.com/ostreedev/ostree">https://github.com/ostreedev/ostree</a>.</p>
<p>However, we do not use the “Merge pull request” button, because we do
not like merge commits for one-patch pull requests, among other
reasons. See <a href="https://github.com/isaacs/github/issues/2">this issue</a>
for more information. Instead, we use an instance of
<a href="https://github.com/servo/homu">Homu</a>, currently known as
<code class="language-plaintext highlighter-rouge">cgwalters-bot</code>.</p>
<p>As a review proceeds, the preferred method is to push <code class="language-plaintext highlighter-rouge">fixup!</code> commits. Any commits committed with the <code class="language-plaintext highlighter-rouge">--fixup</code> option will have have the word <code class="language-plaintext highlighter-rouge">fixup!</code> in its commit title. This is to indicate that this particular commit will be squashed with the commit that was specified in this command, <code class="language-plaintext highlighter-rouge">git commit --fixup <commit ref or hash></code>. Homu knows how to use <code class="language-plaintext highlighter-rouge">--autosquash</code> when performing the final merge.</p>
<p>See the
<a href="https://git-scm.com/docs/git-rebase">Git documentation</a> for more
information.</p>
<p>Alternative methods if you don’t like GitHub (also fully supported):</p>
<ol>
<li>Send mail to <a href="mailto:ostree-list@gnome.org">ostree-list@gnome.org</a>, with the patch attached</li>
<li>Attach them to <a href="https://bugzilla.gnome.org/">https://bugzilla.gnome.org/</a></li>
</ol>
<p>It is likely however once a patch is ready to apply a maintainer
will push it to a GitHub PR, and merge via Homu.</p>
<h2 id="commit-message-style">
<a href="#commit-message-style" class="anchor-heading" aria-labelledby="commit-message-style"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Commit message style
</h2>
<p>Please look at <code class="language-plaintext highlighter-rouge">git log</code> and match the commit log style, which is very
similar to the
<a href="https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git">Linux kernel</a>.</p>
<p>You may use <code class="language-plaintext highlighter-rouge">Signed-off-by</code>, but we’re not requiring it.</p>
<p><strong>General Commit Message Guidelines</strong>:</p>
<ol>
<li>Title
<ul>
<li>Specify the context or category of the changes e.g. <code class="language-plaintext highlighter-rouge">lib</code> for library changes, <code class="language-plaintext highlighter-rouge">docs</code> for document changes, <code class="language-plaintext highlighter-rouge">bin/<command-name></code> for command changes, etc.</li>
<li>Begin the title with the first letter of the first word capitalized.</li>
<li>Aim for less than 50 characters, otherwise 72 characters max.</li>
<li>Do not end the title with a period.</li>
<li>Use an <a href="https://en.wikipedia.org/wiki/Imperative_mood">imperative tone</a>.</li>
</ul>
</li>
<li>Body
<ul>
<li>Separate the body with a blank line after the title.</li>
<li>Begin a paragraph with the first letter of the first word capitalized.</li>
<li>Each paragraph should be formatted within 72 characters.</li>
<li>Content should be about what was changed and why this change was made.</li>
<li>If your commit fixes an issue, the commit message should end with <code class="language-plaintext highlighter-rouge">Closes: #<number></code>.</li>
</ul>
</li>
</ol>
<p>Commit Message example:</p>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><context>: Less than 50 characters <span class="k">for </span>subject title
A paragraph of the body should be within 72 characters.
This paragraph is also less than 72 characters.
</code></pre></div></div>
<p>For more information see <a href="https://chris.beams.io/posts/git-commit/">How to Write a Git Commit Message</a></p>
<p><strong>Editing a Committed Message:</strong></p>
<p>To edit the message from the most recent commit run <code class="language-plaintext highlighter-rouge">git commit --amend</code>. To change older commits on the branch use <code class="language-plaintext highlighter-rouge">git rebase -i</code>. For a successful rebase have the branch track <code class="language-plaintext highlighter-rouge">upstream main</code>. Once the changes have been made and saved, run <code class="language-plaintext highlighter-rouge">git push --force origin <branch-name></code>.</p>
<h2 id="running-the-test-suite">
<a href="#running-the-test-suite" class="anchor-heading" aria-labelledby="running-the-test-suite"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Running the test suite
</h2>
<p>OSTree uses both <code class="language-plaintext highlighter-rouge">make check</code> and supports the
<a href="https://wiki.gnome.org/GnomeGoals/InstalledTests">Installed Tests</a>
model as well (if <code class="language-plaintext highlighter-rouge">--enable-installed-tests</code> is provided).</p>
<h2 id="coding-style">
<a href="#coding-style" class="anchor-heading" aria-labelledby="coding-style"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Coding style
</h2>
<p>Indentation is GNU. Files should start with the appropriate mode lines.</p>
<p>Use GCC <code class="language-plaintext highlighter-rouge">__attribute__((cleanup))</code> wherever possible. If interacting
with a third party library, try defining local cleanup macros.</p>
<p>Use GError and GCancellable where appropriate.</p>
<p>Prefer returning <code class="language-plaintext highlighter-rouge">gboolean</code> to signal success/failure, and have output
values as parameters.</p>
<p>Prefer linear control flow inside functions (aside from standard
loops). In other words, avoid “early exits” or use of <code class="language-plaintext highlighter-rouge">goto</code> besides
<code class="language-plaintext highlighter-rouge">goto out;</code>.</p>
<p>This is an example of an “early exit”:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>static gboolean
myfunc (...)
{
gboolean ret = FALSE;
/* some code */
/* some more code */
if (condition)
return FALSE;
/* some more code */
ret = TRUE;
out:
return ret;
}
</code></pre></div></div>
<p>If you must shortcut, use:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>if (condition)
{
ret = TRUE;
goto out;
}
</code></pre></div></div>
<p>A consequence of this restriction is that you are encouraged to avoid
deep nesting of loops or conditionals. Create internal static helper
functions, particularly inside loops. For example, rather than:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>while (condition)
{
/* some code */
if (condition)
{
for (i = 0; i < somevalue; i++)
{
if (condition)
{
/* deeply nested code */
}
/* more nested code */
}
}
}
</code></pre></div></div>
<p>Instead do this:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>static gboolean
helperfunc (..., GError **error)
{
if (condition)
{
/* deeply nested code */
}
/* more nested code */
return ret;
}
while (condition)
{
/* some code */
if (!condition)
continue;
for (i = 0; i < somevalue; i++)
{
if (!helperfunc (..., i, error))
goto out;
}
}
</code></pre></div></div>
<h2 id="contributing-tutorial">
<a href="#contributing-tutorial" class="anchor-heading" aria-labelledby="contributing-tutorial"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Contributing Tutorial
</h2>
<p>For a detailed walk-through on building, modifying, and testing, see this <a href="/ostree/contributing-tutorial/">tutorial on how to start contributing to OSTree</a>.</p>
<h2 id="release-process">
<a href="#release-process" class="anchor-heading" aria-labelledby="release-process"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Release process
</h2>
<p>Releases can be performed by <a href="https://github.com/ostreedev/ostree/issues/new?labels=kind/release&template=release-checklist.md">creating a new release ticket</a> and following the steps in the checklist there.</p>
<hr>
<footer>
<p class="text-small text-grey-dk-100 mb-0">Copyright © <a href="https://www.redhat.com">Red Hat, Inc.</a> and <a href="https://github.com/ostreedev">others</a>.</p>
<div class="d-flex mt-2">
<p class="text-small text-grey-dk-000 mb-0">
<a href="https://github.com/ostreedev/ostree/tree/main/docs/CONTRIBUTING.md" id="edit-this-page">Edit this page on GitHub</a>
</p>
</div>
</footer>
</div>
</div>
<div class="search-overlay"></div>
</div>
</body>
</html>
|
