diff options
| author | cgwalters <cgwalters@users.noreply.github.com> | 2023-05-03 12:28:36 +0000 |
|---|---|---|
| committer | cgwalters <cgwalters@users.noreply.github.com> | 2023-05-03 12:28:36 +0000 |
| commit | 39b623c8f568d1baaf089175f859c7e83dae8c5a (patch) | |
| tree | ea763f34cfafb24690a1f6fe43b4b3ab86d27aac /CONTRIBUTING/index.html | |
| download | ostree-39b623c8f568d1baaf089175f859c7e83dae8c5a.tar.gz | |
jekyll build from Action 8a2993a9d01cc358e4c2d936ca132174aabdc714gh-pages
Diffstat (limited to 'CONTRIBUTING/index.html')
| -rw-r--r-- | CONTRIBUTING/index.html | 460 |
1 files changed, 460 insertions, 0 deletions
diff --git a/CONTRIBUTING/index.html b/CONTRIBUTING/index.html new file mode 100644 index 00000000..a331a9e5 --- /dev/null +++ b/CONTRIBUTING/index.html @@ -0,0 +1,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> + |