You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
<liclass="toctree-l1 has-children"><aclass="reference internal" href="development_setup.html">Setting up Matplotlib for development</a><details><summary><spanclass="toctree-toggle" role="presentation"><iclass="fa-solid fa-chevron-down"></i></span></summary><ul>
<liclass="toctree-l2"><aclass="reference internal" href="MEP/MEP12.html">MEP12: Improve Gallery and Examples</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="MEP/MEP13.html">MEP13: Use properties for Artists</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="MEP/MEP14.html">MEP14: Text handling</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="MEP/MEP15.html">MEP15: Fix axis autoscaling when limits are specified for one axis only</a></li>
<li><p>When you're ready or need feedback on your code, open a pull request so that the
Matplotlib developers can give feedback and eventually include your suggested
code into the <codeclass="docutils literal notranslate"><spanclass="pre">main</span></code> branch.</p></li>
</ul>
</section>
<sectionid="update-the-main-branch">
<spanid="update-mirror-main"></span><h2>Update the <codeclass="docutils literal notranslate"><spanclass="pre">main</span></code> branch<aclass="headerlink" href="#update-the-main-branch" title="Link to this heading">#</a></h2>
<p>First make sure you have followed <aclass="reference internal" href="development_setup.html#installing-for-devs"><spanclass="std std-ref">Setting up Matplotlib for development</span></a>.</p>
<p>From time to time you should fetch the upstream changes from GitHub:</p>
<p>This will pull down any commits you don't have, and set the remote branches to
point to the right commit.</p>
</section>
<sectionid="make-a-new-feature-branch">
<spanid="make-feature-branch"></span><h2>Make a new feature branch<aclass="headerlink" href="#make-a-new-feature-branch" title="Link to this heading">#</a></h2>
<p>When you are ready to make some changes to the code, you should start a new
branch. Branches that are for a collection of related edits are often called
'feature branches'.</p>
<p>Making a new branch for each set of related changes will make it easier for
someone reviewing your branch to see what you are doing.</p>
<p>Choose an informative name for the branch to remind yourself and the rest of us
what the changes in the branch are for. For example <codeclass="docutils literal notranslate"><spanclass="pre">add-ability-to-fly</span></code>, or
<p>If you started making changes on your local <codeclass="docutils literal notranslate"><spanclass="pre">main</span></code> branch, you can convert the
<p>Generally, you will want to keep your feature branches on your public GitHub
fork of Matplotlib. To do this, you <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">push</span></code> this new branch up to your
GitHub repo. Generally, if you followed the instructions in these pages, and by
default, git will have a link to your fork of the GitHub repo, called
<codeclass="docutils literal notranslate"><spanclass="pre">origin</span></code>. You push up to your own fork with:</p>
<p>From now on git will know that <codeclass="docutils literal notranslate"><spanclass="pre">my-new-feature</span></code> is related to the
<codeclass="docutils literal notranslate"><spanclass="pre">my-new-feature</span></code> branch in the GitHub repo.</p>
<p>If you first opened the pull request from your <codeclass="docutils literal notranslate"><spanclass="pre">main</span></code> branch and then
converted it to a feature branch, you will need to close the original pull
request and open a new pull request from the renamed branch. See
<aclass="reference external" href="https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches#working-with-branches">GitHub: working with branches</a>.</p>
</section>
<sectionid="the-editing-workflow">
<spanid="edit-flow"></span><h2>The editing workflow<aclass="headerlink" href="#the-editing-workflow" title="Link to this heading">#</a></h2>
<olclass="arabic">
<li><p>Make some changes</p></li>
<li><p>Save the changes</p></li>
<li><p>See which files have changed with <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">status</span></code>.
You'll see a listing like this one:</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span># On branch ny-new-feature
# Changed but not updated:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: README
#
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# INSTALL
no changes added to commit (use "git add" and/or "git commit -a")
</pre></div>
</div>
</li>
<li><p>Check what the actual changes are with <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">diff</span></code>.</p></li>
<li><p>Add any new files to version control <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">add</span><spanclass="pre">new_file_name</span></code>.</p></li>
<li><p>To commit <strong>all</strong> modified files into the local copy of your repo, type:</p>
<p>Note the <codeclass="docutils literal notranslate"><spanclass="pre">-am</span></code> options to <codeclass="docutils literal notranslate"><spanclass="pre">commit</span></code>. The <codeclass="docutils literal notranslate"><spanclass="pre">m</span></code> flag signals that you are
going to type a message on the command line. The <codeclass="docutils literal notranslate"><spanclass="pre">a</span></code> flag stages every
file that has been modified, except files listed in <codeclass="docutils literal notranslate"><spanclass="pre">.gitignore</span></code>. For more
information, see <aclass="reference external" href="http://gitready.com/beginner/2009/01/18/the-staging-area.html">why the -a flag?</a> and the
<li><p>To push the changes up to your forked repo on GitHub, do a <codeclass="docutils literal notranslate"><spanclass="pre">git</span>
<spanclass="pre">push</span></code>.</p></li>
</ol>
</section>
<sectionid="open-a-pull-request">
<h2>Open a pull request<aclass="headerlink" href="#open-a-pull-request" title="Link to this heading">#</a></h2>
<p>When you are ready to ask for someone to review your code and consider a merge,
<aclass="reference external" href="https://docs.github.com/pull-requests">submit your Pull Request (PR)</a>.</p>
<p>Enter a title for the set of changes with some explanation of what you've done.
Mention anything you'd like particular attention for - such as a
complicated change or some code you are not happy with.</p>
<p>If you don't think your request is ready to be merged, just say so in your pull
request message and use the "Draft PR" feature of GitHub. This is a good way of
getting some preliminary code review.</p>
</section>
<sectionid="update-a-pull-request">
<spanid="update-pull-request"></span><h2>Update a pull request<aclass="headerlink" href="#update-a-pull-request" title="Link to this heading">#</a></h2>
<p>When updating your pull request after making revisions, instead of adding new
commits, please consider amending your initial commit(s) to keep the commit
<spanid="recovering-from-mess-up"></span><h3>Recover from mistakes<aclass="headerlink" href="#recover-from-mistakes" title="Link to this heading">#</a></h3>
<p>Sometimes, you mess up merges or rebases. Luckily, in git it is
relatively straightforward to recover from such mistakes.</p>
<spanid="rewriting-commit-history"></span><h3>Rewrite commit history<aclass="headerlink" href="#rewrite-commit-history" title="Link to this heading">#</a></h3>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>Do this only for your own feature branches.</p>
</div>
<p>Is there an embarrassing typo in a commit you made? Or perhaps you
made several false starts you don't want posterity to see.</p>
<p>This can be done via <em>interactive rebasing</em>.</p>
<p>Suppose that the commit history looks like this:</p>
<p>and <codeclass="docutils literal notranslate"><spanclass="pre">6ad92e5</span></code> is the last commit in the <codeclass="docutils literal notranslate"><spanclass="pre">cool-feature</span></code> branch. Suppose we
want to make the following changes:</p>
<ulclass="simple">
<li><p>Rewrite the commit message for <codeclass="docutils literal notranslate"><spanclass="pre">13d7934</span></code> to something more sensible.</p></li>
<li><p>Combine the commits <codeclass="docutils literal notranslate"><spanclass="pre">2dec1ac</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">a815645</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">eadc391</span></code> into a single one.</p></li>
</ul>
<p>We do as follows:</p>
<divclass="highlight-bash notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># make a backup of the current state</span>
<p>If it went wrong, recovery is again possible as explained <aclass="reference internal" href="#recovering-from-mess-up"><spanclass="std std-ref">above</span></a>.</p>
<p>If you have not yet pushed this branch to github, you can carry on as normal,
however if you <em>have</em> already pushed this commit see <aclass="reference internal" href="#force-push"><spanclass="std std-ref">Push with force</span></a> for how
to replace your already published commits with the new ones.</p>
</section>
<sectionid="rebase-onto-upstream-main">
<spanid="rebase-on-main"></span><h3>Rebase onto <codeclass="docutils literal notranslate"><spanclass="pre">upstream/main</span></code><aclass="headerlink" href="#rebase-onto-upstream-main" title="Link to this heading">#</a></h3>
<p>Let's say you thought of some work you'd like to do. You
<aclass="reference internal" href="#update-mirror-main"><spanclass="std std-ref">Update the main branch</span></a> and <aclass="reference internal" href="#make-feature-branch"><spanclass="std std-ref">Make a new feature branch</span></a> called
<codeclass="docutils literal notranslate"><spanclass="pre">cool-feature</span></code>. At this stage, <codeclass="docutils literal notranslate"><spanclass="pre">main</span></code> is at some commit, let's call it E.
Now you make some new commits on your <codeclass="docutils literal notranslate"><spanclass="pre">cool-feature</span></code> branch, let's call them
A, B, C. Maybe your changes take a while, or you come back to them after a
while. In the meantime, <codeclass="docutils literal notranslate"><spanclass="pre">main</span></code> has progressed from commit E to commit (say) G:</p>
<p>At this stage you consider merging <codeclass="docutils literal notranslate"><spanclass="pre">main</span></code> into your feature branch, and you
remember that this page sternly advises you not to do that, because the
history will get messy. Most of the time, you can just ask for a review without
worrying about whether <codeclass="docutils literal notranslate"><spanclass="pre">main</span></code> has got a little ahead; however sometimes, the changes in
<codeclass="docutils literal notranslate"><spanclass="pre">main</span></code> might affect your changes, and you need to harmonize them. In this
situation you may prefer to do a rebase.</p>
<p><codeclass="docutils literal notranslate"><spanclass="pre">rebase</span></code> takes your changes (A, B, C) and replays them as if they had been
made to the current state of <codeclass="docutils literal notranslate"><spanclass="pre">main</span></code>. In other words, in this case, it takes
the changes represented by A, B, C and replays them on top of G. After the
<p>See <aclass="reference external" href="https://matthew-brett.github.io/pydagogue/rebase_without_tears.html">rebase without tears</a> for more detail.</p>
<p>To do a rebase on <codeclass="docutils literal notranslate"><spanclass="pre">upstream/main</span></code>:</p>
<divclass="highlight-bash notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># Fetch changes from upstream/main</span>
<p>If it doesn't look good you may need to have a look at
<aclass="reference internal" href="#recovering-from-mess-up"><spanclass="std std-ref">Recover from mistakes</span></a>.</p>
<p>If you have made changes to files that have also changed in <codeclass="docutils literal notranslate"><spanclass="pre">main</span></code>, this may
generate merge conflicts that you need to resolve - see the <aclass="reference external" href="https://git-scm.com/docs/git-rebase">git rebase</a> man
page for some instructions at the end of the "Description" section. There is
some related help on merging in the git user manual - see <aclass="reference external" href="https://schacon.github.io/git/user-manual.html#resolving-a-merge">resolving a merge</a>.</p>
<p>If you have not yet pushed this branch to github, you can carry on as normal,
however if you <em>have</em> already pushed this commit see <aclass="reference internal" href="#force-push"><spanclass="std std-ref">Push with force</span></a> for how
to replace your already published commits with the new ones.</p>
</section>
<sectionid="push-with-force">
<spanid="force-push"></span><h3>Push with force<aclass="headerlink" href="#push-with-force" title="Link to this heading">#</a></h3>
<p>If you have in some way re-written already pushed history (e.g. via
<aclass="reference internal" href="#rewriting-commit-history"><spanclass="std std-ref">Rewrite commit history</span></a> or <aclass="reference internal" href="#rebase-on-main"><spanclass="std std-ref">Rebase onto upstream/main</span></a>) leaving you with
<p>where you have pushed the commits <codeclass="docutils literal notranslate"><spanclass="pre">A,B,C</span></code> to your fork on GitHub (under the
remote name <em>origin</em>) but now have the commits <codeclass="docutils literal notranslate"><spanclass="pre">A'</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">E</span></code> on your local
branch <em>cool-feature</em>. If you try to push the new commits to GitHub, it will
hint:<spanclass="w"></span>See<spanclass="w"></span>the<spanclass="w"></span><spanclass="s1">'Note about fast-forwards'</span><spanclass="w"></span><spanclass="k">in</span><spanclass="w"></span><spanclass="s1">'git push --help'</span><spanclass="w"></span><spanclass="k">for</span><spanclass="w"></span>details.
</pre></div>
</div>
<p>If this push had succeeded, the commits <codeclass="docutils literal notranslate"><spanclass="pre">A</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">B</span></code>, and <codeclass="docutils literal notranslate"><spanclass="pre">C</span></code> would no
longer be referenced by any branch and they would be discarded:</p>
<p>By default <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">push</span></code> helpfully tries to protect you from accidentally
discarding commits by rejecting the push to the remote. When this happens,
GitHub also adds the helpful suggestion to pull the remote changes and then try
pushing again. In some cases, such as if you and a colleague are both
committing and pushing to the same branch, this is a correct course of action.</p>
<p>However, in the case of having intentionally re-written history, we <em>want</em> to
discard the commits on the remote and replace them with the new-and-improved
versions from our local branch. In this case, what we want to do is</p>
<p>which tells git you are aware of the risks and want to do the push anyway. We
recommend using <codeclass="docutils literal notranslate"><spanclass="pre">--force-with-lease</span></code> over the <codeclass="docutils literal notranslate"><spanclass="pre">--force</span></code> flag. The
<codeclass="docutils literal notranslate"><spanclass="pre">--force</span></code> will do the push no matter what, whereas <codeclass="docutils literal notranslate"><spanclass="pre">--force-with-lease</span></code>
will only do the push if the remote branch is where the local <codeclass="docutils literal notranslate"><spanclass="pre">git</span></code> client
thought it was.</p>
<p>Be judicious with force-pushing. It is effectively re-writing published
history, and if anyone has fetched the old commits, it will have a different view
of history which can cause confusion.</p>
</section>
</section>
<sectionid="automated-tests">
<spanid="id2"></span><h2>Automated tests<aclass="headerlink" href="#automated-tests" title="Link to this heading">#</a></h2>
<p>Whenever a pull request is created or updated, various automated test tools
will run on all supported platforms and versions of Python.</p>
<ulclass="simple">
<li><p><aclass="reference external" href="https://tox.readthedocs.io/">tox</a> is not used in the automated testing. It is supported for testing
locally.</p>
</li>
<li><p>Codecov and CodeQL are currently for information only. Their failure is not
necessarily a blocker.</p></li>
</ul>
<p>Make sure the Linting, GitHub Actions, AppVeyor, CircleCI, and Azure pipelines are
passing before merging. All checks are listed at the bottom of the GitHub page of your
<divclass="line">Search the log for <codeclass="docutils literal notranslate"><spanclass="pre">FAILURES</span></code>. Subsequent section should contain information