<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>
<spanid="id1"></span><h1>Development workflow<aclass="headerlink" href="#development-workflow" title="Permalink to this heading">#</a></h1>
<sectionid="workflow-summary">
<h2>Workflow summary<aclass="headerlink" href="#workflow-summary" title="Permalink to this heading">#</a></h2>
<p>To keep your work well organized, with readable history, and in turn make it
easier for project maintainers (that might be you) to see what you've done, and
why you did it, we recommend the following:</p>
<ulclass="simple">
<li><p>Don't use your <codeclass="docutils literal notranslate"><spanclass="pre">main</span></code> branch for anything. Consider deleting it.</p></li>
<li><p>Before starting a new set of changes, fetch all changes from
<codeclass="docutils literal notranslate"><spanclass="pre">upstream/main</span></code>, and start a new <em>feature branch</em> from that.</p></li>
<li><p>Make a new branch for each feature or bug fix — "one task, one branch".</p></li>
<li><p>Name your branch for the purpose of the changes - e.g.
<codeclass="docutils literal notranslate"><spanclass="pre">bugfix-for-issue-14</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">refactor-database-code</span></code>.</p></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>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>It may sound strange, but deleting your own <codeclass="docutils literal notranslate"><spanclass="pre">main</span></code> branch can help reduce
confusion about which branch you are on. See <aclass="reference external" href="https://matthew-brett.github.io/pydagogue/gh_delete_master.html">deleting main on GitHub</a> for
details.</p>
</div>
</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="Permalink 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="Permalink 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>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>
git<spanclass="w"></span>commit<spanclass="w"></span>-am<spanclass="w"></span><spanclass="s1">'NF - some message'</span>
git<spanclass="w"></span>push
</pre></div>
</div>
</section>
<sectionid="in-more-detail">
<h3>In more detail<aclass="headerlink" href="#in-more-detail" title="Permalink to this heading">#</a></h3>
<olclass="arabic">
<li><p>Make some 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 all modified files into the local copy of your repo,, do
<codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">commit</span><spanclass="pre">-am</span><spanclass="pre">'A</span><spanclass="pre">commit</span><spanclass="pre">message'</span></code>. 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 just signals that you're going to type a
message on the command line. The <codeclass="docutils literal notranslate"><spanclass="pre">a</span></code> flag — you can just take on
faith — or see <aclass="reference external" href="http://gitready.com/beginner/2009/01/18/the-staging-area.html">why the -a flag?</a>. The
<aclass="reference external" href="https://git-scm.com/docs/git-commit">git commit</a> manual page might also be
useful.</p></li>
<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>
</section>
<sectionid="open-a-pull-request">
<h2>Open a pull request<aclass="headerlink" href="#open-a-pull-request" title="Permalink 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
<h2>Some other things you might want to do<aclass="headerlink" href="#some-other-things-you-might-want-to-do" title="Permalink to this heading">#</a></h2>
<sectionid="explore-your-repository">
<h3>Explore your repository<aclass="headerlink" href="#explore-your-repository" title="Permalink to this heading">#</a></h3>
<p>To see a graphical representation of the repository branches and
<spanid="recovering-from-mess-up"></span><h3>Recovering from mess-ups<aclass="headerlink" href="#recovering-from-mess-ups" title="Permalink 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>
<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">Pushing, with force</span></a> for how
to replace your already published commits with the new ones.</p>
</section>
<sectionid="rebasing-on-upstream-main">
<spanid="rebase-on-main"></span><h3>Rebasing on <codeclass="docutils literal notranslate"><spanclass="pre">upstream/main</span></code><aclass="headerlink" href="#rebasing-on-upstream-main" title="Permalink 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">Recovering from mess-ups</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">Pushing, with force</span></a> for how
to replace your already published commits with the new ones.</p>
</section>
<sectionid="pushing-with-force">
<spanid="force-push"></span><h3>Pushing, with force<aclass="headerlink" href="#pushing-with-force" title="Permalink 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">Rewriting commit history</span></a> or <aclass="reference internal" href="#rebase-on-main"><spanclass="std std-ref">Rebasing on 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