<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" />
<title>Contribution getting started</title>
<style type="text/css">
/*
:Author: David Goodger (goodger@python.org)
:Id: $Id: html4css1.css 7614 2013-02-21 15:55:51Z milde $
:Copyright: This stylesheet has been placed in the public domain.
Default cascading style sheet for the HTML output of Docutils.
See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/
/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
border: 0 }
table.borderless td, table.borderless th {
/* Override padding for "table.docutils td" with "! important".
The right padding separates the table cells. */
padding: 0 0.5em 0 0 ! important }
.first {
/* Override more specific margin styles with "! important". */
margin-top: 0 ! important }
.last, .with-subtitle {
margin-bottom: 0 ! important }
.hidden {
display: none }
a.toc-backref {
text-decoration: none ;
color: black }
blockquote.epigraph {
margin: 2em 5em ; }
dl.docutils dd {
margin-bottom: 0.5em }
object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
overflow: hidden;
}
/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
font-weight: bold }
*/
div.abstract {
margin: 2em 5em }
div.abstract p.topic-title {
font-weight: bold ;
text-align: center }
div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
margin: 2em ;
border: medium outset ;
padding: 1em }
div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
font-weight: bold ;
font-family: sans-serif }
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title, .code .error {
color: red ;
font-weight: bold ;
font-family: sans-serif }
/* Uncomment (and remove this text!) to get reduced vertical space in
compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
margin-bottom: 0.5em }
div.compound .compound-last, div.compound .compound-middle {
margin-top: 0.5em }
*/
div.dedication {
margin: 2em 5em ;
text-align: center ;
font-style: italic }
div.dedication p.topic-title {
font-weight: bold ;
font-style: normal }
div.figure {
margin-left: 2em ;
margin-right: 2em }
div.footer, div.header {
clear: both;
font-size: smaller }
div.line-block {
display: block ;
margin-top: 1em ;
margin-bottom: 1em }
div.line-block div.line-block {
margin-top: 0 ;
margin-bottom: 0 ;
margin-left: 1.5em }
div.sidebar {
margin: 0 0 0.5em 1em ;
border: medium outset ;
padding: 1em ;
background-color: #ffffee ;
width: 40% ;
float: right ;
clear: right }
div.sidebar p.rubric {
font-family: sans-serif ;
font-size: medium }
div.system-messages {
margin: 5em }
div.system-messages h1 {
color: red }
div.system-message {
border: medium outset ;
padding: 1em }
div.system-message p.system-message-title {
color: red ;
font-weight: bold }
div.topic {
margin: 2em }
h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
margin-top: 0.4em }
h1.title {
text-align: center }
h2.subtitle {
text-align: center }
hr.docutils {
width: 75% }
img.align-left, .figure.align-left, object.align-left {
clear: left ;
float: left ;
margin-right: 1em }
img.align-right, .figure.align-right, object.align-right {
clear: right ;
float: right ;
margin-left: 1em }
img.align-center, .figure.align-center, object.align-center {
display: block;
margin-left: auto;
margin-right: auto;
}
.align-left {
text-align: left }
.align-center {
clear: both ;
text-align: center }
.align-right {
text-align: right }
/* reset inner alignment in figures */
div.align-right {
text-align: inherit }
/* div.align-center * { */
/* text-align: left } */
ol.simple, ul.simple {
margin-bottom: 1em }
ol.arabic {
list-style: decimal }
ol.loweralpha {
list-style: lower-alpha }
ol.upperalpha {
list-style: upper-alpha }
ol.lowerroman {
list-style: lower-roman }
ol.upperroman {
list-style: upper-roman }
p.attribution {
text-align: right ;
margin-left: 50% }
p.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.rubric {
font-weight: bold ;
font-size: larger ;
color: maroon ;
text-align: center }
p.sidebar-title {
font-family: sans-serif ;
font-weight: bold ;
font-size: larger }
p.sidebar-subtitle {
font-family: sans-serif ;
font-weight: bold }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
font: inherit }
pre.literal-block, pre.doctest-block, pre.math, pre.code {
margin-left: 2em ;
margin-right: 2em }
pre.code .ln { color: grey; } /* line numbers */
pre.code, code { background-color: #eeeeee }
pre.code .comment, code .comment { color: #5C6576 }
pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold }
pre.code .literal.string, code .literal.string { color: #0C5404 }
pre.code .name.builtin, code .name.builtin { color: #352B84 }
pre.code .deleted, code .deleted { background-color: #DEB0A1}
pre.code .inserted, code .inserted { background-color: #A3D289}
span.classifier {
font-family: sans-serif ;
font-style: oblique }
span.classifier-delimiter {
font-family: sans-serif ;
font-weight: bold }
span.interpreted {
font-family: sans-serif }
span.option {
white-space: nowrap }
span.pre {
white-space: pre }
span.problematic {
color: red }
span.section-subtitle {
/* font-size relative to parent (h1..h6 element) */
font-size: 80% }
table.citation {
border-left: solid 1px gray;
margin-left: 1px }
table.docinfo {
margin: 2em 4em }
table.docutils {
margin-top: 0.5em ;
margin-bottom: 0.5em }
table.footnote {
border-left: solid 1px black;
margin-left: 1px }
table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
padding-left: 0.5em ;
padding-right: 0.5em ;
vertical-align: top }
table.docutils th.field-name, table.docinfo th.docinfo-name {
font-weight: bold ;
text-align: left ;
white-space: nowrap ;
padding-left: 0 }
/* "booktabs" style (no vertical lines) */
table.docutils.booktabs {
border: 0px;
border-top: 2px solid;
border-bottom: 2px solid;
border-collapse: collapse;
}
table.docutils.booktabs * {
border: 0px;
}
table.docutils.booktabs th {
border-bottom: thin solid;
text-align: left;
}
h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
font-size: 100% }
ul.auto-toc {
list-style-type: none }
</style>
</head>
<body>
<div class="document" id="contribution-getting-started">
<h1 class="title">Contribution getting started</h1>
<p>Contributions are highly welcomed and appreciated. Every little help counts,
so do not hesitate!</p>
<div class="contents topic" id="contribution-links">
<p class="topic-title first">Contribution links</p>
<ul class="simple">
<li><a class="reference internal" href="#feature-requests-and-feedback" id="id6">Feature requests and feedback</a></li>
<li><a class="reference internal" href="#report-bugs" id="id7">Report bugs</a></li>
<li><a class="reference internal" href="#fix-bugs" id="id8">Fix bugs</a></li>
<li><a class="reference internal" href="#implement-features" id="id9">Implement features</a></li>
<li><a class="reference internal" href="#write-documentation" id="id10">Write documentation</a></li>
<li><a class="reference internal" href="#submitting-plugins-to-pytest-dev" id="id11">Submitting Plugins to pytest-dev</a></li>
<li><a class="reference internal" href="#preparing-pull-requests-on-github" id="id12">Preparing Pull Requests on GitHub</a></li>
</ul>
</div>
<div class="section" id="feature-requests-and-feedback">
<span id="submitfeedback"></span><h1><a class="toc-backref" href="#id6">Feature requests and feedback</a></h1>
<p>Do you like pytest? Share some love on Twitter or in your blog posts!</p>
<p>We'd also like to hear about your propositions and suggestions. Feel free to
<a class="reference external" href="https://github.com/pytest-dev/pytest/issues">submit them as issues</a> and:</p>
<ul class="simple">
<li>Explain in detail how they should work.</li>
<li>Keep the scope as narrow as possible. This will make it easier to implement.</li>
</ul>
</div>
<div class="section" id="report-bugs">
<span id="reportbugs"></span><h1><a class="toc-backref" href="#id7">Report bugs</a></h1>
<p>Report bugs for pytest in the <a class="reference external" href="https://github.com/pytest-dev/pytest/issues">issue tracker</a>.</p>
<p>If you are reporting a bug, please include:</p>
<ul class="simple">
<li>Your operating system name and version.</li>
<li>Any details about your local setup that might be helpful in troubleshooting,
specifically Python interpreter version,
installed libraries and pytest version.</li>
<li>Detailed steps to reproduce the bug.</li>
</ul>
<p>If you can write a demonstration test that currently fails but should pass (xfail),
that is a very useful commit to make as well, even if you can't find how
to fix the bug yet.</p>
</div>
<div class="section" id="fix-bugs">
<span id="fixbugs"></span><h1><a class="toc-backref" href="#id8">Fix bugs</a></h1>
<p>Look through the GitHub issues for bugs. Here is a filter you can use:
<a class="reference external" href="https://github.com/pytest-dev/pytest/labels/bug">https://github.com/pytest-dev/pytest/labels/bug</a></p>
<p><a href="#id1"><span class="problematic" id="id2">:ref:`Talk <contact>`</span></a> to developers to find out how you can fix specific bugs.</p>
<div class="system-message" id="id1">
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">CONTRIBUTING.rst</tt>, line 54); <em><a href="#id2">backlink</a></em></p>
Unknown interpreted text role "ref".</div>
<p>Don't forget to check the issue trackers of your favourite plugins, too!</p>
</div>
<div class="section" id="implement-features">
<span id="writeplugins"></span><h1><a class="toc-backref" href="#id9">Implement features</a></h1>
<p>Look through the GitHub issues for enhancements. Here is a filter you can use:
<a class="reference external" href="https://github.com/pytest-dev/pytest/labels/enhancement">https://github.com/pytest-dev/pytest/labels/enhancement</a></p>
<p><a href="#id3"><span class="problematic" id="id4">:ref:`Talk <contact>`</span></a> to developers to find out how you can implement specific
features.</p>
<div class="system-message" id="id3">
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">CONTRIBUTING.rst</tt>, line 66); <em><a href="#id4">backlink</a></em></p>
Unknown interpreted text role "ref".</div>
</div>
<div class="section" id="write-documentation">
<h1><a class="toc-backref" href="#id10">Write documentation</a></h1>
<p>Pytest could always use more documentation. What exactly is needed?</p>
<ul class="simple">
<li>More complementary documentation. Have you perhaps found something unclear?</li>
<li>Documentation translations. We currently have only English.</li>
<li>Docstrings. There can never be too many of them.</li>
<li>Blog posts, articles and such -- they're all very appreciated.</li>
</ul>
<p>You can also edit documentation files directly in the GitHub web interface,
without using a local copy. This can be convenient for small fixes.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p>Build the documentation locally with the following command:</p>
<pre class="code bash literal-block">
$ tox -e docs
</pre>
<p>The built documentation should be available in the <tt class="docutils literal">doc/en/_build/</tt>.</p>
<p class="last">Where 'en' refers to the documentation language.</p>
</div>
</div>
<div class="section" id="submitting-plugins-to-pytest-dev">
<span id="submitplugin"></span><h1><a class="toc-backref" href="#id11">Submitting Plugins to pytest-dev</a></h1>
<p>Pytest development of the core, some plugins and support code happens
in repositories living under the <tt class="docutils literal"><span class="pre">pytest-dev</span></tt> organisations:</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pytest-dev">pytest-dev on GitHub</a></li>
<li><a class="reference external" href="https://bitbucket.org/pytest-dev">pytest-dev on Bitbucket</a></li>
</ul>
<p>All pytest-dev Contributors team members have write access to all contained
repositories. Pytest core and plugins are generally developed
using <a class="reference internal" href="#pull-requests">pull requests</a> to respective repositories.</p>
<p>The objectives of the <tt class="docutils literal"><span class="pre">pytest-dev</span></tt> organisation are:</p>
<ul class="simple">
<li>Having a central location for popular pytest plugins</li>
<li>Sharing some of the maintenance responsibility (in case a maintainer no
longer wishes to maintain a plugin)</li>
</ul>
<p>You can submit your plugin by subscribing to the <a class="reference external" href="https://mail.python.org/mailman/listinfo/pytest-dev">pytest-dev mail list</a> and writing a
mail pointing to your existing pytest plugin repository which must have
the following:</p>
<ul class="simple">
<li>PyPI presence with a <tt class="docutils literal">setup.py</tt> that contains a license, <tt class="docutils literal">pytest-</tt>
prefixed name, version number, authors, short and long description.</li>
<li>a <tt class="docutils literal">tox.ini</tt> for running tests using <a class="reference external" href="http://tox.testrun.org">tox</a>.</li>
<li>a <tt class="docutils literal">README.txt</tt> describing how to use the plugin and on which
platforms it runs.</li>
<li>a <tt class="docutils literal">LICENSE.txt</tt> file or equivalent containing the licensing
information, with matching info in <tt class="docutils literal">setup.py</tt>.</li>
<li>an issue tracker for bug reports and enhancement requests.</li>
<li>a <a class="reference external" href="http://keepachangelog.com/">changelog</a></li>
</ul>
<p>If no contributor strongly objects and two agree, the repository can then be
transferred to the <tt class="docutils literal"><span class="pre">pytest-dev</span></tt> organisation.</p>
<p>Here's a rundown of how a repository transfer usually proceeds
(using a repository named <tt class="docutils literal"><span class="pre">joedoe/pytest-xyz</span></tt> as example):</p>
<ul class="simple">
<li><tt class="docutils literal">joedoe</tt> transfers repository ownership to <tt class="docutils literal"><span class="pre">pytest-dev</span></tt> administrator <tt class="docutils literal">calvin</tt>.</li>
<li><tt class="docutils literal">calvin</tt> creates <tt class="docutils literal"><span class="pre">pytest-xyz-admin</span></tt> and <tt class="docutils literal"><span class="pre">pytest-xyz-developers</span></tt> teams, inviting <tt class="docutils literal">joedoe</tt> to both as <strong>maintainer</strong>.</li>
<li><tt class="docutils literal">calvin</tt> transfers repository to <tt class="docutils literal"><span class="pre">pytest-dev</span></tt> and configures team access:<ul>
<li><tt class="docutils literal"><span class="pre">pytest-xyz-admin</span></tt> <strong>admin</strong> access;</li>
<li><tt class="docutils literal"><span class="pre">pytest-xyz-developers</span></tt> <strong>write</strong> access;</li>
</ul>
</li>
</ul>
<p>The <tt class="docutils literal"><span class="pre">pytest-dev/Contributors</span></tt> team has write access to all projects, and
every project administrator is in it. We recommend that each plugin has at least three
people who have the right to release to PyPI.</p>
<p>Repository owners can rest assured that no <tt class="docutils literal"><span class="pre">pytest-dev</span></tt> administrator will ever make
releases of your repository or take ownership in any way, except in rare cases
where someone becomes unresponsive after months of contact attempts.
As stated, the objective is to share maintenance and avoid "plugin-abandon".</p>
</div>
<div class="section" id="preparing-pull-requests-on-github">
<span id="id5"></span><span id="pull-requests"></span><h1><a class="toc-backref" href="#id12">Preparing Pull Requests on GitHub</a></h1>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">What is a "pull request"? It informs project's core developers about the
changes you want to review and merge. Pull requests are stored on
<a class="reference external" href="https://github.com/pytest-dev/pytest/pulls">GitHub servers</a>.
Once you send a pull request, we can discuss its potential modifications and
even add more commits to it later on.</p>
</div>
<p>There's an excellent tutorial on how Pull Requests work in the
<a class="reference external" href="https://help.github.com/articles/using-pull-requests/">GitHub Help Center</a>,
but here is a simple overview:</p>
<ol class="arabic">
<li><p class="first">Fork the
<a class="reference external" href="https://github.com/pytest-dev/pytest">pytest GitHub repository</a>. It's
fine to use <tt class="docutils literal">pytest</tt> as your fork repository name because it will live
under your user.</p>
</li>
<li><p class="first">Clone your fork locally using <a class="reference external" href="https://git-scm.com/">git</a> and create a branch:</p>
<pre class="literal-block">
$ git clone git@github.com:YOUR_GITHUB_USERNAME/pytest.git
$ cd pytest
# now, to fix a bug create your own branch off "master":
$ git checkout -b your-bugfix-branch-name master
# or to instead add a feature create your own branch off "features":
$ git checkout -b your-feature-branch-name features
</pre>
<p>Given we have "major.minor.micro" version numbers, bugfixes will usually
be released in micro releases whereas features will be released in
minor releases and incompatible changes in major releases.</p>
<p>If you need some help with Git, follow this quick start
guide: <a class="reference external" href="https://git.wiki.kernel.org/index.php/QuickStart">https://git.wiki.kernel.org/index.php/QuickStart</a></p>
</li>
<li><p class="first">Install tox</p>
<p>Tox is used to run all the tests and will automatically setup virtualenvs
to run the tests in.
(will implicitly use <a class="reference external" href="http://www.virtualenv.org/en/latest/">http://www.virtualenv.org/en/latest/</a>):</p>
<pre class="literal-block">
$ pip install tox
</pre>
</li>
<li><p class="first">Run all the tests</p>
<p>You need to have Python 2.7 and 3.5 available in your system. Now
running tests is as simple as issuing this command:</p>
<pre class="literal-block">
$ tox -e linting,py27,py35
</pre>
<p>This command will run tests via the "tox" tool against Python 2.7 and 3.5
and also perform "lint" coding-style checks.</p>
</li>
<li><p class="first">You can now edit your local working copy.</p>
<p>You can now make the changes you want and run the tests again as necessary.</p>
<p>To run tests on Python 2.7 and pass options to pytest (e.g. enter pdb on
failure) to pytest you can do:</p>
<pre class="literal-block">
$ tox -e py27 -- --pdb
</pre>
<p>Or to only run tests in a particular test module on Python 3.5:</p>
<pre class="literal-block">
$ tox -e py35 -- testing/test_config.py
</pre>
</li>
<li><p class="first">Commit and push once your tests pass and you are happy with your change(s):</p>
<pre class="literal-block">
$ git commit -a -m "<commit message>"
$ git push -u
</pre>
<p>Make sure you add a message to <tt class="docutils literal">CHANGELOG.rst</tt> and add yourself to
<tt class="docutils literal">AUTHORS</tt>. If you are unsure about either of these steps, submit your
pull request and we'll help you fix it up.</p>
</li>
<li><p class="first">Finally, submit a pull request through the GitHub website using this data:</p>
<pre class="literal-block">
head-fork: YOUR_GITHUB_USERNAME/pytest
compare: your-branch-name
base-fork: pytest-dev/pytest
base: master # if it's a bugfix
base: features # if it's a feature
</pre>
</li>
</ol>
</div>
</div>
</body>
</html>
distrib
>
Mageia
>
6
>
x86_64
>
media
>
core-release
>
by-pkgid
>
00f3932a0958a2e02f84eb3e3a606495
>
files
>
186
