<!DOCTYPE html>

<html class="writer-html5" lang="en" >

<head>

<meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />

<meta name="viewport" content="width=device-width, initial-scale=1.0" />

<title>Contributing to POT &mdash; POT Python Optimal Transport 0.8.1.0 documentation</title>

<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />

<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />

<link rel="stylesheet" href="../_static/sg_gallery.css" type="text/css" />

<link rel="stylesheet" href="../_static/sg_gallery-binder.css" type="text/css" />

<link rel="stylesheet" href="../_static/sg_gallery-dataframe.css" type="text/css" />

<link rel="stylesheet" href="../_static/sg_gallery-rendered-html.css" type="text/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/doctools.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="Code of Conduct" href="CODE_OF_CONDUCT.html" />

<link rel="prev" title="Releases" href="../releases.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"> POT Python Optimal Transport

</a>

<div class="version">

0.8.1.0

</div>

<div role="search">

<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">

<input type="text" name="q" placeholder="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="../index.html">POT: Python Optimal Transport</a></li>

<li class="toctree-l1"><a class="reference internal" href="../quickstart.html">Quick start guide</a></li>

<li class="toctree-l1"><a class="reference internal" href="../all.html">API and modules</a></li>

<li class="toctree-l1"><a class="reference internal" href="../auto_examples/index.html">Examples gallery</a></li>

<li class="toctree-l1"><a class="reference internal" href="../releases.html">Releases</a></li>

<li class="toctree-l1 current"><a class="current reference internal" href="#">Contributing to POT</a><ul>

<li class="toctree-l2"><a class="reference internal" href="#how-to-contribute">How to contribute</a></li>

<li class="toctree-l2"><a class="reference internal" href="#pull-request-checklist">Pull Request Checklist</a></li>

<li class="toctree-l2"><a class="reference internal" href="#filing-bugs">Filing bugs</a></li>

<li class="toctree-l2"><a class="reference internal" href="#new-contributor-tips">New contributor tips</a></li>

<li class="toctree-l2"><a class="reference internal" href="#documentation">Documentation</a></li>

</ul>

</li>

<li class="toctree-l1"><a class="reference internal" href="CODE_OF_CONDUCT.html">Code of Conduct</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">POT Python Optimal Transport</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"></a> &raquo;</li>

<li>Contributing to POT</li>

<li class="wy-breadcrumbs-aside">

<a href="../_sources/.github/CONTRIBUTING.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">

<section id="contributing-to-pot">

<h1>Contributing to POT<a class="headerlink" href="#contributing-to-pot" title="Permalink to this headline"></a></h1>

<p>First off, thank you for considering contributing to POT.</p>

<section id="how-to-contribute">

<h2>How to contribute<a class="headerlink" href="#how-to-contribute" title="Permalink to this headline"></a></h2>

<p>The preferred workflow for contributing to POT is to fork the

<a class="reference external" href="https://github.com/rflamary/POT">main repository</a> on

GitHub, clone, and develop on a branch. Steps:</p>

<ol class="arabic">

<li><p>Fork the <a class="reference external" href="https://github.com/rflamary/POT">project repository</a>

by clicking on the ‘Fork’ button near the top right of the page. This creates

a copy of the code under your GitHub user account. For more details on

how to fork a repository see <a class="reference external" href="https://help.github.com/articles/fork-a-repo/">this guide</a>.</p></li>

<li><p>Clone your fork of the POT repo from your GitHub account to your local disk:</p>

<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ git clone git@github.com:YourLogin/POT.git

$ <span class="nb">cd</span> POT

</pre></div>

</div>

</li>

<li><p>Create a <code class="docutils literal notranslate"><span class="pre">feature</span></code> branch to hold your development changes:</p>

<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ git checkout -b my-feature

</pre></div>

</div>

<p>Always use a <code class="docutils literal notranslate"><span class="pre">feature</span></code> branch. It’s good practice to never work on the <code class="docutils literal notranslate"><span class="pre">master</span></code> branch!</p>

</li>

<li><p>Develop the feature on your feature branch. Add changed files using <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">add</span></code> and then <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span></code> files:</p>

<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ git add modified_files

$ git commit

</pre></div>

</div>

<p>to record your changes in Git, then push the changes to your GitHub account with:</p>

<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ git push -u origin my-feature

</pre></div>

</div>

</li>

<li><p>Follow <a class="reference external" href="https://help.github.com/articles/creating-a-pull-request-from-a-fork">these instructions</a>

to create a pull request from your fork. This will send an email to the committers.</p></li>

</ol>

<p>(If any of the above seems like magic to you, please look up the

<a class="reference external" href="https://git-scm.com/documentation">Git documentation</a> on the web, or ask a friend or another contributor for help.)</p>

</section>

<section id="pull-request-checklist">

<h2>Pull Request Checklist<a class="headerlink" href="#pull-request-checklist" title="Permalink to this headline"></a></h2>

<p>We recommended that your contribution complies with the

following rules before you submit a pull request:</p>

<ul class="simple">

<li><p>Follow the PEP8 Guidelines.</p></li>

<li><p>If your pull request addresses an issue, please use the pull request title

to describe the issue and mention the issue number in the pull request description. This will make sure a link back to the original issue is

created.</p></li>

<li><p>All public methods should have informative docstrings with sample

usage presented as doctests when appropriate.</p></li>

<li><p>Please prefix the title of your pull request with <code class="docutils literal notranslate"><span class="pre">[MRG]</span></code> (Ready for

Merge), if the contribution is complete and ready for a detailed review.

Two core developers will review your code and change the prefix of the pull

request to <code class="docutils literal notranslate"><span class="pre">[MRG</span> <span class="pre">+</span> <span class="pre">1]</span></code> and <code class="docutils literal notranslate"><span class="pre">[MRG</span> <span class="pre">+</span> <span class="pre">2]</span></code> on approval, making it eligible

for merging. An incomplete contribution – where you expect to do more work before

receiving a full review – should be prefixed <code class="docutils literal notranslate"><span class="pre">[WIP]</span></code> (to indicate a work

in progress) and changed to <code class="docutils literal notranslate"><span class="pre">[MRG]</span></code> when it matures. WIPs may be useful

to: indicate you are working on something to avoid duplicated work,

request broad review of functionality or API, or seek collaborators.

WIPs often benefit from the inclusion of a

<a class="reference external" href="https://github.com/blog/1375-task-lists-in-gfm-issues-pulls-comments">task list</a>

in the PR description.</p></li>

<li><p>When adding additional functionality, provide at least one

example script in the <code class="docutils literal notranslate"><span class="pre">examples/</span></code> folder. Have a look at other

examples for reference. Examples should demonstrate why the new

functionality is useful in practice and, if possible, compare it

to other methods available in POT.</p></li>

<li><p>Documentation and high-coverage tests are necessary for enhancements to be

accepted. Bug-fixes or new features should be provided with

<a class="reference external" href="https://en.wikipedia.org/wiki/Non-regression_testing">non-regression tests</a>.

These tests verify the correct behavior of the fix or feature. In this

manner, further modifications on the code base are granted to be consistent

with the desired behavior.

For the Bug-fixes case, at the time of the PR, this tests should fail for

the code base in master and pass for the PR code.</p></li>

<li><p>At least one paragraph of narrative documentation with links to

references in the literature (with PDF links when possible) and

the example.</p></li>

</ul>

<p>You can also check for common programming errors with the following

tools:</p>

<ul class="simple">

<li><p>No pyflakes warnings, check with:</p></li>

</ul>

<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ pip install pyflakes

$ pyflakes path/to/module.py

</pre></div>

</div>

<ul class="simple">

<li><p>No PEP8 warnings, check with:</p></li>

</ul>

<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ pip install pep8

$ pep8 path/to/module.py

</pre></div>

</div>

<ul class="simple">

<li><p>AutoPEP8 can help you fix some of the easy redundant errors:</p></li>

</ul>

<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ pip install autopep8

$ autopep8 path/to/pep8.py

</pre></div>

</div>

<p>Bonus points for contributions that include a performance analysis with

a benchmark script and profiling output (please report on the mailing

list or on the GitHub issue).</p>

</section>

<section id="filing-bugs">

<h2>Filing bugs<a class="headerlink" href="#filing-bugs" title="Permalink to this headline"></a></h2>

<p>We use Github issues to track all bugs and feature requests; feel free to

open an issue if you have found a bug or wish to see a feature implemented.</p>

<p>It is recommended to check that your issue complies with the

following rules before submitting:</p>

<ul class="simple">

<li><p>Verify that your issue is not being currently addressed by other

<a class="reference external" href="https://github.com/rflamary/POT/issues?q=">issues</a>

or <a class="reference external" href="https://github.com/rflamary/POT/pulls?q=">pull requests</a>.</p></li>

<li><p>Please ensure all code snippets and error messages are formatted in

appropriate code blocks.

See <a class="reference external" href="https://help.github.com/articles/creating-and-highlighting-code-blocks">Creating and highlighting code blocks</a>.</p></li>

<li><p>Please include your operating system type and version number, as well

as your Python, POT, numpy, and scipy versions. This information

can be found by running the following code snippet:</p></li>

</ul>

<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">platform</span><span class="p">;</span> <span class="nb">print</span><span class="p">(</span><span class="n">platform</span><span class="o">.</span><span class="n">platform</span><span class="p">())</span>

<span class="kn">import</span> <span class="nn">sys</span><span class="p">;</span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Python&quot;</span><span class="p">,</span> <span class="n">sys</span><span class="o">.</span><span class="n">version</span><span class="p">)</span>

<span class="kn">import</span> <span class="nn">numpy</span><span class="p">;</span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;NumPy&quot;</span><span class="p">,</span> <span class="n">numpy</span><span class="o">.</span><span class="n">__version__</span><span class="p">)</span>

<span class="kn">import</span> <span class="nn">scipy</span><span class="p">;</span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;SciPy&quot;</span><span class="p">,</span> <span class="n">scipy</span><span class="o">.</span><span class="n">__version__</span><span class="p">)</span>

<span class="kn">import</span> <span class="nn">ot</span><span class="p">;</span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;POT&quot;</span><span class="p">,</span> <span class="n">ot</span><span class="o">.</span><span class="n">__version__</span><span class="p">)</span>

</pre></div>

</div>

<ul class="simple">

<li><p>Please be specific about what estimators and/or functions are involved

and the shape of the data, as appropriate; please include a

<a class="reference external" href="http://stackoverflow.com/help/mcve">reproducible</a> code snippet

or link to a <a class="reference external" href="https://gist.github.com">gist</a>. If an exception is raised,

please provide the traceback.</p></li>

</ul>

</section>

<section id="new-contributor-tips">

<h2>New contributor tips<a class="headerlink" href="#new-contributor-tips" title="Permalink to this headline"></a></h2>

<p>A great way to start contributing to POT is to pick an item

from the list of <a class="reference external" href="https://github.com/rflamary/POT/issues?labels=Easy">Easy issues</a>

in the issue tracker. Resolving these issues allow you to start

contributing to the project without much prior knowledge. Your

assistance in this area will be greatly appreciated by the more

experienced developers as it helps free up their time to concentrate on

other issues.</p>

</section>

<section id="documentation">

<h2>Documentation<a class="headerlink" href="#documentation" title="Permalink to this headline"></a></h2>

<p>We are glad to accept any sort of documentation: function docstrings,

reStructuredText documents (like this one), tutorials, etc.

reStructuredText documents live in the source code repository under the

doc/ directory.</p>

<p>You can edit the documentation using any text editor and then generate

the HTML output by typing <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">html</span></code> from the <code class="docutils literal notranslate"><span class="pre">docs/</span></code> directory.

Alternatively, <code class="docutils literal notranslate"><span class="pre">make</span></code> can be used to quickly generate the

documentation without the example gallery with <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">html-noplot</span></code>. The resulting HTML files will

be placed in <code class="docutils literal notranslate"><span class="pre">docs/build/html/</span></code> and are viewable in a web browser.</p>

<p>For building the documentation, you will need

<a class="reference external" href="http://sphinx.pocoo.org/">sphinx</a>,

<a class="reference external" href="http://matplotlib.org/">matplotlib</a>, and

<a class="reference external" href="http://pillow.readthedocs.io/en/latest/">pillow</a>.</p>

<p>When you are writing documentation, it is important to keep a good

compromise between mathematical and algorithmic details, and give

intuition to the reader on what the algorithm does. It is best to always

start with a small paragraph with a hand-waving explanation of what the

method does to the data and a figure (coming from an example)

illustrating it.</p>

<p>This Contribution guide is strongly inpired by the one of the <a class="reference external" href="https://github.com/scikit-learn/scikit-learn">scikit-learn</a> team.</p>

</section>

</section>

</div>

</div>

<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">

<a href="../releases.html" class="btn btn-neutral float-left" title="Releases" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>

<a href="CODE_OF_CONDUCT.html" class="btn btn-neutral float-right" title="Code of Conduct" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>

</div>

<hr/>

<div role="contentinfo">

<p>&#169; Copyright 2016-2021, Rémi Flamary, Nicolas Courty.</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>

<div class="rst-versions" data-toggle="rst-versions" role="note"

aria-label="versions">

<!-- add shift_up to the class for force viewing -->

<span class="rst-current-version" data-toggle="rst-current-version">

<span class="fa fa-book"> Python Optimal Transport</span>

versions

<span class="fa fa-caret-down"></span>

</span>

<div class="rst-other-versions"><!-- Inserted RTD Footer -->

<div class="injected">

<dl>

<dt>Versions</dt>

<dd><a href="https://pythonot.github.io/">Release</a></dd>

<dd><a href="https://pythonot.github.io/master">Development</a></dd>

</dl>

<dl>

<dt>On GitHub</dt>

<dd>

<a href="https://github.com/PythonOT/POT">Code on Github</a>

</dd>

</dl>

<hr>

</div>

</div>

</div><script>

jQuery(function () {

SphinxRtdTheme.Navigation.enable(true);

});

</script>

</body>

</html>