Upgrade macos
This commit is contained in:
Bassem Girgis
@@ -0,0 +1,324 @@
|
||||
<!DOCTYPE html>
|
||||
<html class="writer-html5" lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>12.2. GitHub, Git, and related topics — OpenPMIx 5.0.5 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/css/theme.css" />
|
||||
|
||||
|
||||
<!--[if lt IE 9]>
|
||||
<script src="../_static/js/html5shiv.min.js"></script>
|
||||
<![endif]-->
|
||||
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/jquery.js"></script>
|
||||
<script src="../_static/underscore.js"></script>
|
||||
<script src="../_static/_sphinx_javascript_frameworks_compat.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<script src="../_static/js/theme.js"></script>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="12.3. Compiler Pickyness by Default" href="compiler-pickyness.html" />
|
||||
<link rel="prev" title="12.1. Prerequisites" href="prerequisites.html" />
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav">
|
||||
<div class="wy-grid-for-nav">
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search" >
|
||||
|
||||
|
||||
|
||||
<a href="../index.html" class="icon icon-home">
|
||||
OpenPMIx
|
||||
</a>
|
||||
<div role="search">
|
||||
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
|
||||
<ul class="current">
|
||||
<li class="toctree-l1"><a class="reference internal" href="../quickstart.html">1. Quick start</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../getting-help.html">2. Getting help</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../release-notes/index.html">3. Release notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../exceptions.html">4. Exceptions to the PMIx Standard</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../installing-pmix/index.html">5. Building and installing PMIx</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../how-things-work/index.html">6. How Things Work</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../release-notes.html">7. Release Notes</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../history.html">8. History</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../versions.html">9. Version Numbers and Binary Compatibility</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../mca.html">10. The Modular Component Architecture (MCA)</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../building-apps/index.html">11. Building PMIx applications</a></li>
|
||||
<li class="toctree-l1 current"><a class="reference internal" href="index.html">12. Developer’s guide</a><ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html">12.1. Prerequisites</a></li>
|
||||
<li class="toctree-l2 current"><a class="current reference internal" href="#">12.2. GitHub, Git, and related topics</a><ul>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#github">12.2.1. GitHub</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#git-commits-open-source-contributor-s-declaration">12.2.2. Git commits: open source / contributor’s declaration</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#git-branch-scheme">12.2.3. Git branch scheme</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#ci-testing">12.2.4. CI (testing)</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="compiler-pickyness.html">12.3. Compiler Pickyness by Default</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="autogen.html">12.4. Running <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code></a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="building-pmix.html">12.5. Building PMIx</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="terminology.html">12.6. OpenPMIx terminology</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="source-code.html">12.7. Source code</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="frameworks.html">12.8. Internal frameworks</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="gnu-autotools.html">12.9. Manually installing the GNU Autootools</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="sphinx.html">12.10. Installing and running Sphinx (building the OpenPMIx docs)</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html">12.11. ReStructured Text for those who know Markdown</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../contributing.html">13. Contributing to OpenPMIx</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../license.html">14. License</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../security.html">15. OpenPMIx Security Policy</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../news/index.html">16. News</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../man/index.html">17. OpenPMIx manual pages</a></li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="../index.html">OpenPMIx</a>
|
||||
</nav>
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="Page navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
|
||||
<li class="breadcrumb-item"><a href="index.html"><span class="section-number">12. </span>Developer’s guide</a></li>
|
||||
<li class="breadcrumb-item active"><span class="section-number">12.2. </span>GitHub, Git, and related topics</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="../_sources/developers/git-github.rst.txt" rel="nofollow"> View page source</a>
|
||||
</li>
|
||||
</ul>
|
||||
<hr/>
|
||||
</div>
|
||||
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
||||
<div itemprop="articleBody">
|
||||
|
||||
<style>
|
||||
.wy-table-responsive table td,.wy-table-responsive table th{white-space:normal}
|
||||
</style><div class="section" id="github-git-and-related-topics">
|
||||
<h1><span class="section-number">12.2. </span>GitHub, Git, and related topics<a class="headerlink" href="#github-git-and-related-topics" title="Permalink to this heading"></a></h1>
|
||||
<div class="section" id="github">
|
||||
<h2><span class="section-number">12.2.1. </span>GitHub<a class="headerlink" href="#github" title="Permalink to this heading"></a></h2>
|
||||
<p>PMIx’s Git repository is <a class="reference external" href="https://github.com/openpmix/openpmix">hosted at GitHub</a>.</p>
|
||||
<ol class="arabic">
|
||||
<li><p>First, you will need a Git client. We recommend getting the latest
|
||||
version available. If you do not have the command <code class="docutils literal notranslate"><span class="pre">git</span></code> in your
|
||||
path, you will likely need to download and install Git.</p></li>
|
||||
<li><p><a class="reference external" href="https://github.com/openpmix/openpmix/">openpmix</a> is the main PMIx
|
||||
repository where most active development is done. Git clone this
|
||||
repository. Note that the use of the <code class="docutils literal notranslate"><span class="pre">--recursive</span></code> CLI option is
|
||||
necessary because PMIx uses Git submodules:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>shell$ git clone --recursive https://github.com/openpmix/openpmix.git
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
</ol>
|
||||
<p>Note that Git is natively capable of using many forms of web
|
||||
proxies. If your network setup requires the user of a web proxy,
|
||||
<a class="reference external" href="https://git-scm.com/">consult the Git documentation for more details</a>.</p>
|
||||
</div>
|
||||
<div class="section" id="git-commits-open-source-contributor-s-declaration">
|
||||
<h2><span class="section-number">12.2.2. </span>Git commits: open source / contributor’s declaration<a class="headerlink" href="#git-commits-open-source-contributor-s-declaration" title="Permalink to this heading"></a></h2>
|
||||
<p>In order to remain open source, all new commits to the PMIx
|
||||
repository must include a <code class="docutils literal notranslate"><span class="pre">Signed-off-by:</span></code> line, indicating the
|
||||
submitter’s agreement to the <a class="reference internal" href="../contributing.html#contributing-contributors-declaration-label"><span class="std std-ref">PMIx Contributor’s Declaration</span></a>.</p>
|
||||
<div class="admonition tip">
|
||||
<p class="admonition-title">Tip</p>
|
||||
<p>You can use the <code class="docutils literal notranslate"><span class="pre">-s</span></code> option to <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span></code> to
|
||||
automatically add the <code class="docutils literal notranslate"><span class="pre">Signed-off-by:</span></code> line to your commit
|
||||
message.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="git-branch-scheme">
|
||||
<span id="git-github-branch-scheme-label"></span><h2><span class="section-number">12.2.3. </span>Git branch scheme<a class="headerlink" href="#git-branch-scheme" title="Permalink to this heading"></a></h2>
|
||||
<p>Generally, PMIx has two types of branches in its Git repository:</p>
|
||||
<ol class="arabic simple">
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">master</span></code>:</p>
|
||||
<ul class="simple">
|
||||
<li><p>All active development occurs on the <code class="docutils literal notranslate"><span class="pre">master</span></code> branch (new features,
|
||||
bug fixes, etc.).</p></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><p>Release branches of the form <code class="docutils literal notranslate"><span class="pre">vMAJOR.MINOR.x</span></code> (e.g., <code class="docutils literal notranslate"><span class="pre">v4.0.x</span></code>,
|
||||
<code class="docutils literal notranslate"><span class="pre">v4.1.x</span></code>, <code class="docutils literal notranslate"><span class="pre">v5.0.x</span></code>).</p>
|
||||
<ul class="simple">
|
||||
<li><p>The <code class="docutils literal notranslate"><span class="pre">.x</span></code> suffix indicates that this branch is used to create
|
||||
all releases in the PMIx vMAJOR.MINOR series.</p></li>
|
||||
<li><p>Periodically, the PMIx community will make a new release
|
||||
branch, typically from <code class="docutils literal notranslate"><span class="pre">master</span></code>.</p></li>
|
||||
<li><p>A Git tag of the form <code class="docutils literal notranslate"><span class="pre">vMAJOR.MINOR.RELEASE</span></code> is used to
|
||||
indicate the specific commit on a release branch from where
|
||||
official PMIx release tarball was created (e.g., <code class="docutils literal notranslate"><span class="pre">v4.1.0</span></code>,
|
||||
<code class="docutils literal notranslate"><span class="pre">v4.1.1</span></code>, <code class="docutils literal notranslate"><span class="pre">v4.1.2</span></code>, etc.).</p></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ol>
|
||||
<p>Once a bug is fixed or a new feature is implemented on <code class="docutils literal notranslate"><span class="pre">master</span></code>, it is
|
||||
cherry-picked over to the relevant release branch(es).</p>
|
||||
<div class="admonition attention">
|
||||
<p class="admonition-title">Attention</p>
|
||||
<p>It may seem odd to some, but the PMIx community
|
||||
development model does <em>not</em> PR bug fixes or new
|
||||
features directly to release branches. Instead,
|
||||
initial bug-fix / feature PRs are generally first made
|
||||
to <code class="docutils literal notranslate"><span class="pre">master</span></code>.</p>
|
||||
<p>This helps us ensure that future releases (with
|
||||
<code class="docutils literal notranslate"><span class="pre">master</span></code> as a Git ancestor) will contain the bug fix /
|
||||
feature.</p>
|
||||
</div>
|
||||
<p>For example:</p>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>shell$<span class="w"> </span>git<span class="w"> </span>checkout<span class="w"> </span>master
|
||||
shell$<span class="w"> </span>git<span class="w"> </span>pull<span class="w"> </span>--rebase
|
||||
shell$<span class="w"> </span>git<span class="w"> </span>checkout<span class="w"> </span>pr/bug-fix
|
||||
|
||||
<span class="c1"># ... make changes / fix a bug / etc. ...</span>
|
||||
|
||||
shell$<span class="w"> </span>git<span class="w"> </span>add<span class="w"> </span>...
|
||||
shell$<span class="w"> </span>git<span class="w"> </span>commit<span class="w"> </span>-s<span class="w"> </span>...
|
||||
shell$<span class="w"> </span>git<span class="w"> </span>push<span class="w"> </span>myfork
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>At this point, you go create a PR from your fork’s <code class="docutils literal notranslate"><span class="pre">pr/bug-fix</span></code>
|
||||
branch to the PMIx community GitHub repo <code class="docutils literal notranslate"><span class="pre">master</span></code> branch. Work
|
||||
with the community to get the PR completed and merged. Then you can
|
||||
open a new PR to cherry pick the Git commits from that bug fix to each
|
||||
of the relevant release branches.</p>
|
||||
<p>Depending on how far the release branch has diverged from <code class="docutils literal notranslate"><span class="pre">master</span></code>,
|
||||
there may be some porting effort involved in the cherry-pick.</p>
|
||||
<p>For example, if your bug fix on <code class="docutils literal notranslate"><span class="pre">master</span></code> is comprised of a single Git
|
||||
commit hash <code class="docutils literal notranslate"><span class="pre">123abc</span></code>:</p>
|
||||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="c1"># Fetch all upstream git activity, including the merge of the "master" PR.</span>
|
||||
shell$<span class="w"> </span>get<span class="w"> </span>fetch<span class="w"> </span>--all
|
||||
|
||||
<span class="c1"># Check out the target release branch, and advance to the most recent commit.</span>
|
||||
shell$<span class="w"> </span>git<span class="w"> </span>checkout<span class="w"> </span>v5.0.x
|
||||
shell$<span class="w"> </span>git<span class="w"> </span>pull<span class="w"> </span>--rebase
|
||||
|
||||
<span class="c1"># Make a branch for your bug fix</span>
|
||||
shell$<span class="w"> </span>git<span class="w"> </span>checkout<span class="w"> </span>-b<span class="w"> </span>pr/v5.0.x/bug-fix
|
||||
<span class="c1"># Cherry pick the commit from the "master" branch</span>
|
||||
shell$<span class="w"> </span>git<span class="w"> </span>cherry-pick<span class="w"> </span>-x<span class="w"> </span>123abc
|
||||
<span class="c1"># Push to your fork</span>
|
||||
shell$<span class="w"> </span>git<span class="w"> </span>push<span class="w"> </span>myfork
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The PMIx development community <em>requires</em> adding the following
|
||||
line to the commit message of cherry-picked commits on release
|
||||
branches:</p>
|
||||
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>(cherry picked from commit [git_hash_of_original_commit])
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>Note the use of the <code class="docutils literal notranslate"><span class="pre">-x</span></code> option to <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">cherry-pick</span></code>.
|
||||
This option automatically adds the <code class="docutils literal notranslate"><span class="pre">(cherry</span> <span class="pre">picked</span> <span class="pre">from</span>
|
||||
<span class="pre">...)</span></code> line to your commit message.</p>
|
||||
</div>
|
||||
<div class="tip admonition">
|
||||
<p class="admonition-title">Rationale</p>
|
||||
<p>Git does not actually store any meta data about Git cherry-picks in
|
||||
the commit. Having a standardized text line containing the source
|
||||
Git commit hash in the commit messages helps the PMIx
|
||||
development community track where commits came from on release
|
||||
branches, and therefore allows us to check whether all relevant
|
||||
commits have been ported to a given release branch.</p>
|
||||
</div>
|
||||
<p>Once your commits are ready and pushed up to your fork, make a PR to
|
||||
the target release branch.</p>
|
||||
<div class="admonition warning">
|
||||
<p class="admonition-title">Warning</p>
|
||||
<p>A GitHub PR CI job checks all commits on release branches
|
||||
for the <code class="docutils literal notranslate"><span class="pre">(cherry</span> <span class="pre">picked</span> <span class="pre">from...)</span></code> line. It will also
|
||||
ensure that the Git hash cited in that line actually
|
||||
exists on the <code class="docutils literal notranslate"><span class="pre">master</span></code> branch.</p>
|
||||
<p>This check ensures that commits are not made to release
|
||||
branches before their corresponding <code class="docutils literal notranslate"><span class="pre">master</span></code> PR was
|
||||
merged.</p>
|
||||
</div>
|
||||
<p>All this being said, sometimes there is a need for a non-cherry-picked
|
||||
commit on a release branch. E.g., sometimes a release branch has
|
||||
diverged so much that the bug no longer exists on <code class="docutils literal notranslate"><span class="pre">master</span></code>. It would
|
||||
therefore not make sense — or even be impossible — to
|
||||
commit the bug fix in question to <code class="docutils literal notranslate"><span class="pre">master</span></code>.</p>
|
||||
<p>In such cases, make a regular PR to the target branch (with commits
|
||||
that do <em>not</em> include <code class="docutils literal notranslate"><span class="pre">(cherry</span> <span class="pre">picked</span> <span class="pre">from</span> <span class="pre">...)</span></code> lines). In the PR
|
||||
description, add a line with the following token:</p>
|
||||
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>bot:notacherrypick
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>This tells the GitHub CI job that this PR contains commits that are
|
||||
not cherry-picked from <code class="docutils literal notranslate"><span class="pre">master</span></code>.</p>
|
||||
<div class="admonition warning">
|
||||
<p class="admonition-title">Warning</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">bot:notacherrypick</span></code> should only be used when
|
||||
absolutely necessary. It is not a license to avoid
|
||||
the process of PR’ing to <code class="docutils literal notranslate"><span class="pre">master</span></code> first.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="ci-testing">
|
||||
<h2><span class="section-number">12.2.4. </span>CI (testing)<a class="headerlink" href="#ci-testing" title="Permalink to this heading"></a></h2>
|
||||
<p>The PMIx community generally runs a bunch of tests on each PR
|
||||
(Continuous Integration / CI). These tests are a mixture of
|
||||
GitHub Actions and other CI systems (e.g., Jenkins). Examples
|
||||
include (but are not limited to):</p>
|
||||
<blockquote>
|
||||
<div><ul class="simple">
|
||||
<li><p>Check each Git commit for bozo email addresses</p></li>
|
||||
<li><p>Check that each Git commit contains a <code class="docutils literal notranslate"><span class="pre">Signed-off-by</span></code> line</p></li>
|
||||
<li><p>Check that commits on release branches contain a cherry-pick
|
||||
notice</p></li>
|
||||
<li><p>Build and publish the docs</p></li>
|
||||
<li><p>Build PMIx in a variety of environments and run sanity tests
|
||||
with that installation</p></li>
|
||||
</ul>
|
||||
</div></blockquote>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="prerequisites.html" class="btn btn-neutral float-left" title="12.1. Prerequisites" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="compiler-pickyness.html" class="btn btn-neutral float-right" title="12.3. Compiler Pickyness by Default" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<p>© Copyright 2014-2025, The OpenPMIx Community.</p>
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
|
||||
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
|
||||
provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user