| Server IP : 82.208.35.60 / Your IP : 216.73.217.116 Web Server : Apache/2.4.55 (FreeBSD) OpenSSL/1.1.1q-freebsd PHP/7.3.31 System : FreeBSD server7.d2m.cz 12.4-RELEASE-p9 FreeBSD 12.4-RELEASE-p9 GENERIC amd64 User : studiokobylisy_cz ( 1008) PHP Version : 7.3.31 Disable Function : NONE MySQL : OFF | cURL : ON | WGET : OFF | Perl : OFF | Python : OFF | Sudo : OFF | Pkexec : OFF Directory : /usr/local/share/doc/requests-toolbelt/ |
Upload File : |
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Contributing to this project — requests_toolbelt 0.8.0 documentation</title>
<script type="text/javascript" src="_static/js/modernizr.min.js"></script>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'0.8.0',
LANGUAGE:'None',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Transport Adapters" href="adapters.html" />
<link rel="prev" title="requests toolbelt" href="user.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"> requests_toolbelt
</a>
<div class="version">
0.8.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="main navigation">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="user.html">requests toolbelt</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Contributing to this project</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#checklist">Checklist</a></li>
<li class="toctree-l2"><a class="reference internal" href="#contributor-code-of-conduct">Contributor Code of Conduct</a></li>
<li class="toctree-l2"><a class="reference internal" href="#how-to-add-tests">How To Add Tests</a></li>
<li class="toctree-l2"><a class="reference internal" href="#how-to-run-the-tests">How To Run The Tests</a></li>
<li class="toctree-l2"><a class="reference internal" href="#how-to-build-the-documentation">How To Build The Documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="#example-commit-message">Example Commit Message</a></li>
<li class="toctree-l2"><a class="reference internal" href="#footnotes">Footnotes</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="adapters.html">Transport Adapters</a></li>
<li class="toctree-l1"><a class="reference internal" href="authentication.html">Authentication</a></li>
<li class="toctree-l1"><a class="reference internal" href="deprecated.html">Deprecated Requests Utilities</a></li>
<li class="toctree-l1"><a class="reference internal" href="downloadutils.html">Utilities for Downloading Streaming Responses</a></li>
<li class="toctree-l1"><a class="reference internal" href="dumputils.html">Utilities for Dumping Information About Responses</a></li>
<li class="toctree-l1"><a class="reference internal" href="formdata.html">Utilities for Enhanced Form-Data Serialization</a></li>
<li class="toctree-l1"><a class="reference internal" href="exceptions.html">Custom Toolbelt Exceptions</a></li>
<li class="toctree-l1"><a class="reference internal" href="sessions.html">Specialized Sessions</a></li>
<li class="toctree-l1"><a class="reference internal" href="threading.html">Using requests with Threading</a></li>
<li class="toctree-l1"><a class="reference internal" href="uploading-data.html">Uploading Data</a></li>
<li class="toctree-l1"><a class="reference internal" href="user-agent.html">User-Agent Constructor</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">requests_toolbelt</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html">Docs</a> »</li>
<li>Contributing to this project</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/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">
<div class="section" id="contributing-to-this-project">
<h1>Contributing to this project<a class="headerlink" href="#contributing-to-this-project" title="Permalink to this headline">¶</a></h1>
<div class="section" id="checklist">
<h2>Checklist<a class="headerlink" href="#checklist" title="Permalink to this headline">¶</a></h2>
<ol class="arabic simple">
<li>All potential contributors must read the <a class="reference internal" href="#code-of-conduct"><span class="std std-ref">Contributor Code of Conduct</span></a> and follow
it</li>
<li>Fork the repository on <a class="reference external" href="https://github.com/sigmavirus24/requests-toolbelt">GitHub</a> or <a class="reference external" href="https://gitlab.com/sigmavirus24/toolbelt">GitLab</a></li>
<li>Create a new branch, e.g., <code class="docutils literal"><span class="pre">git</span> <span class="pre">checkout</span> <span class="pre">-b</span> <span class="pre">bug/12345</span></code></li>
<li>Fix the bug and add tests (if applicable <a class="footnote-reference" href="#id5" id="id1">[1]</a>, see <a class="reference internal" href="#how-to-add-tests"><span class="std std-ref">How To Add Tests</span></a>)</li>
<li>Run the tests (see <a class="reference internal" href="#how-to-run-tests"><span class="std std-ref">How To Run The Tests</span></a> below)</li>
<li>Add documentation (as necessary) for your change</li>
<li>Build the documentation to check for errors and formatting (see
<a class="reference internal" href="#how-to-build-the-docs"><span class="std std-ref">How To Build The Documentation</span></a> below)</li>
<li>Add yourself to the <code class="file docutils literal"><span class="pre">AUTHORS.rst</span></code> (unless you’re already there)</li>
<li>Commit it. Follow these rules in your commit message:<ul>
<li>Keep the subject line under 50 characters</li>
<li>Use an imperative verb to start the commit</li>
<li>Use an empty line between the subject and the message</li>
<li>Describe the <em>why</em> in detail in the message portion of the commit</li>
<li>Wrap the lines of the message at 72 characters</li>
<li>Add the appropriate “Closes #12345” syntax to autoclose the issue it
fixed (if it closes an issue)</li>
<li>See <a class="reference internal" href="#example-commit-message"><span class="std std-ref">Example Commit Message</span></a> below</li>
</ul>
</li>
<li>Push it to your fork</li>
<li>Create a request for us to merge your contribution</li>
</ol>
<p>After this last step, it is possible that we may leave feedback in the form of
review comments. When addressing these comments, you can follow two
strategies:</p>
<ul class="simple">
<li>Amend/rebase your changes into an existing commit</li>
<li>Create a new commit with a different message <a class="footnote-reference" href="#id6" id="id2">[2]</a> describing the changes in
that commit and push it to your branch</li>
</ul>
<p>This project is not opinionated about which approach you should prefer. We
only ask that you are aware of the following:</p>
<ul class="simple">
<li>Neither GitHub nor GitLab notifies us that you have pushed new changes. A
friendly ping is encouraged</li>
<li>If you continue to use the same branch that you created the request from,
both GitHub and GitLab will update the request on the website. You do
<strong>not</strong> need to create a new request for the new changes.</li>
</ul>
</div>
<div class="section" id="contributor-code-of-conduct">
<span id="code-of-conduct"></span><h2>Contributor Code of Conduct<a class="headerlink" href="#contributor-code-of-conduct" title="Permalink to this headline">¶</a></h2>
<p>As contributors and maintainers of this project, and in the interest of
fostering an open and welcoming community, we pledge to respect all
people who contribute through reporting issues, posting feature
requests, updating documentation, submitting pull requests or patches,
and other activities.</p>
<p>We are committed to making participation in this project a
harassment-free experience for everyone, regardless of level of
experience, gender, gender identity and expression, sexual orientation,
disability, personal appearance, body size, race, ethnicity, age,
religion, or nationality.</p>
<p>Examples of unacceptable behavior by participants include:</p>
<ul class="simple">
<li>The use of sexualized language or imagery</li>
<li>Personal attacks</li>
<li>Trolling or insulting/derogatory comments</li>
<li>Public or private harassment</li>
<li>Publishing other’s private information, such as physical or electronic
addresses, without explicit permission</li>
<li>Other unethical or unprofessional conduct</li>
</ul>
<p>Project maintainers have the right and responsibility to remove, edit,
or reject comments, commits, code, wiki edits, issues, and other
contributions that are not aligned to this Code of Conduct, or to ban
temporarily or permanently any contributor for other behaviors that they
deem inappropriate, threatening, offensive, or harmful.</p>
<p>By adopting this Code of Conduct, project maintainers commit themselves
to fairly and consistently applying these principles to every aspect of
managing this project. Project maintainers who do not follow or enforce
the Code of Conduct may be permanently removed from the project team.</p>
<p>This code of conduct applies both within project spaces and in public
spaces when an individual is representing the project or its community.</p>
<p>Instances of abusive, harassing, or otherwise unacceptable behavior may
be reported by contacting a project maintainer at <a class="reference external" href="mailto:graffatcolmingov%40gmail.com">graffatcolmingov<span>@</span>gmail<span>.</span>com</a>.
All complaints will be reviewed and investigated and will
result in a response that is deemed necessary and appropriate to the
circumstances. Maintainers are obligated to maintain confidentiality
with regard to the reporter of an incident.</p>
<p>This Code of Conduct is adapted from the <a class="reference external" href="http://contributor-covenant.org">Contributor Covenant</a>, version
1.3.0, available at <a class="reference external" href="http://contributor-covenant.org/version/1/3/0/">http://contributor-covenant.org/version/1/3/0/</a></p>
</div>
<div class="section" id="how-to-add-tests">
<span id="id3"></span><h2>How To Add Tests<a class="headerlink" href="#how-to-add-tests" title="Permalink to this headline">¶</a></h2>
<p>We use <a class="reference external" href="http://pytest.org/latest/">pytest</a> to run tests and to simplify how we write tests. If you’re
fixing a bug in an existing please find tests for that module or feature and
add to them. Most tests live in the <code class="docutils literal"><span class="pre">tests</span></code> directory. If you’re adding a
new feature in a new submodule, please create a new module of test code. For
example, if you’re adding a submodule named <code class="docutils literal"><span class="pre">foo</span></code> then you would create
<code class="docutils literal"><span class="pre">tests/test_foo.py</span></code> which will contain the tests for the <code class="docutils literal"><span class="pre">foo</span></code> submodule.</p>
</div>
<div class="section" id="how-to-run-the-tests">
<span id="how-to-run-tests"></span><h2>How To Run The Tests<a class="headerlink" href="#how-to-run-the-tests" title="Permalink to this headline">¶</a></h2>
<p>Run the tests in this project using <a class="reference external" href="https://tox.readthedocs.org/en/latest/">tox</a>. Before you run the tests, ensure
you have installed tox either using your system package manager (e.g., apt,
yum, etc.), or your prefered python installer (e.g., pip).</p>
<p>Then run the tests on at least Python 2.7 and Python 3.x, e.g.,</p>
<div class="code highlight-default"><div class="highlight"><pre><span></span>$ tox -e py27,py34
</pre></div>
</div>
<p>Finally run one, or both, of the flake8 style enforcers, e.g.,</p>
<div class="code highlight-default"><div class="highlight"><pre><span></span>$ tox -e py27-flake8
# or
$ tox -e py34-flake8
</pre></div>
</div>
<p>It is preferable if you run both to catch syntax errors that might occur in
Python 2 or Python 3 (based on how familiar you are with the common subset of
language from both).</p>
<p>Tox will manage virtual environments and dependencies for you so it will be
the only dependency you need to install to contribute to this project.</p>
</div>
<div class="section" id="how-to-build-the-documentation">
<span id="how-to-build-the-docs"></span><h2>How To Build The Documentation<a class="headerlink" href="#how-to-build-the-documentation" title="Permalink to this headline">¶</a></h2>
<p>To build the docs, you need to ensure tox is installed and then you may run</p>
<div class="code highlight-default"><div class="highlight"><pre><span></span>$ tox -e docs
</pre></div>
</div>
<p>This will build the documentation into <code class="docutils literal"><span class="pre">docs/_build/html</span></code>. If you then run</p>
<div class="code highlight-default"><div class="highlight"><pre><span></span>$ python2.7 -m SimpleHTTPServer
# or
$ python3.4 -m http.server
</pre></div>
</div>
<p>from that directory, you can view the docs locally at <a class="reference external" href="http://localhost:8000/">http://localhost:8000/</a>.</p>
</div>
<div class="section" id="example-commit-message">
<span id="id4"></span><h2>Example Commit Message<a class="headerlink" href="#example-commit-message" title="Permalink to this headline">¶</a></h2>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">Allow</span> <span class="n">users</span> <span class="n">to</span> <span class="n">use</span> <span class="n">the</span> <span class="n">frob</span> <span class="n">when</span> <span class="n">uploading</span> <span class="n">data</span>
<span class="n">When</span> <span class="n">uploading</span> <span class="n">data</span> <span class="k">with</span> <span class="n">FooBar</span><span class="p">,</span> <span class="n">users</span> <span class="n">may</span> <span class="n">need</span> <span class="n">to</span> <span class="n">use</span> <span class="n">the</span> <span class="n">frob</span> <span class="n">method</span>
<span class="n">to</span> <span class="n">ensure</span> <span class="n">that</span> <span class="n">pieces</span> <span class="n">of</span> <span class="n">data</span> <span class="n">are</span> <span class="ow">not</span> <span class="n">munged</span><span class="o">.</span>
<span class="n">Closes</span> <span class="c1">#1234567</span>
</pre></div>
</div>
</div>
<div class="section" id="footnotes">
<h2>Footnotes<a class="headerlink" href="#footnotes" title="Permalink to this headline">¶</a></h2>
<table class="docutils footnote" frame="void" id="id5" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>You might not need tests if you’re updating documentation, fixing a
typo, or updating a docstring. If you’re fixing a bug, please add
tests.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id6" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td>If each commit has the same message, the reviewer may ask you to
squash your commits or may squash them for you and perform a manual
merge.</td></tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="adapters.html" class="btn btn-neutral float-right" title="Transport Adapters" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="user.html" class="btn btn-neutral float-left" title="requests toolbelt" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
© Copyright 2015, Ian Cordasco, Cory Benfield
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>