shaba/ostree
1
0
Fork 0
mirror of https://github.com/ostreedev/ostree.git synced 2025-01-03 05:18:24 +03:00
Code Issues Projects Releases Wiki Activity
gh-pages
ostree/CONTRIBUTING/index.html
cgwalters 29f572ec18 jekyll build from Action ac6ba43922
2024-05-30 16:49:28 +00:00

463 lines
20 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!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.5" />
<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/atomic-rollbacks/" class="nav-list-link">Atomic Rollbacks</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/var/" class="nav-list-link">OSTree and /var handling</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/authenticated-repos/" class="nav-list-link">Handling access to authenticated remote 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/copying-deltas/" class="nav-list-link">Static deltas for offline updates</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"><a href="/ostree/related-projects/" class="nav-list-link">Related Projects</a></li><li class="nav-list-item"><a href="/ostree/composefs/" class="nav-list-link">Using composefs with OSTree</a></li><li class="nav-list-item"><a href="/ostree/bootloaders/" class="nav-list-link">Bootloaders</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>
<!-- SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) -->
<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 &lt;commit ref or hash&gt;</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/&lt;command-name&gt;</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: #&lt;number&gt;</code>.</li>
</ul>
</li>
</ol>
<p>Commit Message example:</p>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>&lt;context&gt;: 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 &lt;branch-name&gt;</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 &lt; 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 &lt; 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&amp;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 &copy; <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>
Reference in New Issue View Git Blame Copy Permalink