From 524025216469d75b44050ca84d28b6ab03bc7049 Mon Sep 17 00:00:00 2001 From: Piotr Banaszkiewicz Date: Wed, 22 Jan 2014 11:24:58 +0100 Subject: [PATCH 1/4] New enthusiastic contribution guide based on Audreyr's cookiecutter-pypackage Audrey's code is BSD, so there should be no problem with licensing. I've covered: * contribution types (with hints) * steps to start with pytest development * testing pytest * basics of hg --HG-- branch : contributiondocs --- doc/en/contents.txt | 2 +- doc/en/contribute.txt | 122 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 123 insertions(+), 1 deletion(-) create mode 100644 doc/en/contribute.txt diff --git a/doc/en/contents.txt b/doc/en/contents.txt index 169524483..80d71af7d 100644 --- a/doc/en/contents.txt +++ b/doc/en/contents.txt @@ -16,7 +16,7 @@ Full pytest documentation plugins example/index talks - develop + contribute funcarg_compare.txt announce/index diff --git a/doc/en/contribute.txt b/doc/en/contribute.txt new file mode 100644 index 000000000..f51f55e05 --- /dev/null +++ b/doc/en/contribute.txt @@ -0,0 +1,122 @@ +.. _contributing: + +============ +Contributing +============ + +Contributions are highly welcomed and appreciated. Every little help counts, +so do not hesitate! + +Types of contributions +====================== + +Submit feedback for developers +------------------------------ + +Do you like py.test? Share some love on Twitter or in your blog posts! + +We'd also like to hear about your propositions and suggestions. Feel free to +submit them as issues `here `__ and: + +* Set the "kind" to "enhancement" or "proposal" so that we can quickly find + about them. +* Explain in detail how they should work. +* Keep the scope as narrow as possible. This will make it easier to implement. +* If you have required skills and/or knowledge, you can always contribute to + these issues! + +Report bugs +----------- + +Report bugs at https://bitbucket.org/hpk42/pytest/issues. + +If you are reporting a bug, please include: + +* Your operating system name and version. +* Any details about your local setup that might be helpful in troubleshooting, + specifically Python interpreter version, + installed libraries and py.test version. +* Detailed steps to reproduce the bug. + +Fix bugs +-------- + +Look through the BitBucket issues for bugs. Here is sample filter you can use: +https://bitbucket.org/hpk42/pytest/issues?status=new&status=open&kind=bug + +:ref:'Talk ' to developers to find out how you can fix specific bugs. + +Implement features +------------------ + +Look through the BitBucket issues for enhancements. Here is sample filter you +can use: +https://bitbucket.org/hpk42/pytest/issues?status=new&status=open&kind=enhancement + +:ref:'Talk ' to developers to find out how you can implement specific +features. + +Write documentation +------------------- + +py.test could always use more documentation. What exactly is needed? + +* More complementary documentation. Have you perhaps found something unclear? +* Documentation translations. We currently have English and Japanese versions. +* Docstrings. There's never too much of them. +* Blog posts, articles and such -- they're all very appreciated. + +Getting started for contributing +================================ + +1. Fork the py.test repository on BitBucket. +.. _checkout: +2. Clone your fork locally:: + + $ hg clone ssh://hg@bitbucket.org/your_name_here/pytest + +3. Install your local copy into a virtualenv. Assuming you have + ``virtualenvwrapper`` (http://virtualenvwrapper.readthedocs.org) installed:: + + $ mkvirtualenv pytest + $ cd pytest/ + $ python setup.py develop + + If that last command complains about not finding the required version + of "py" then you need to use the development pypi repository:: + + $ python setup.py develop -i http://pypi.testrun.org + +4. Create a branch for local development:: + + $ hg branch name-of-your-bugfix-or-feature + + Now you can make your changes locally. + +5. When you're done making changes, check that all of them pass all the tests + (including PEP8 and different Python interpreter versions). It's as simple + as issuing this one command:: + + $ tox + + The least minimum of required Python tests to pass is Python 2.7 and + Python 3.3:: + + $ tox -e py27,py33 + + If you don't seem to have ``tox`` installed, issue this from inside your + virtualenv:: + + $ pip install tox + + You also need to have Python 3.3 and 2.7 available in your system. + +6. Commit your changes and push your branch to BitBucket:: + + $ hg add . + $ hg commit + $ hg push --new-branch -r . + +7. Submit a pull request through the BitBucket website. + +.. include:: links.inc From c2c44f0ffc659ebdd1a1faf334c845aefdd371e1 Mon Sep 17 00:00:00 2001 From: Piotr Banaszkiewicz Date: Wed, 22 Jan 2014 11:37:02 +0100 Subject: [PATCH 2/4] Moved contribution guide to the rootdir/CONTRIBUTING.txt --HG-- branch : contributiondocs --- CONTRIBUTING.txt | 119 +++++++++++++++++++++++++++++++++++++++++ doc/en/contribute.txt | 121 +----------------------------------------- 2 files changed, 120 insertions(+), 120 deletions(-) create mode 100644 CONTRIBUTING.txt diff --git a/CONTRIBUTING.txt b/CONTRIBUTING.txt new file mode 100644 index 000000000..6b1e4f206 --- /dev/null +++ b/CONTRIBUTING.txt @@ -0,0 +1,119 @@ + +============ +Contributing +============ + +Contributions are highly welcomed and appreciated. Every little help counts, +so do not hesitate! + +Types of contributions +====================== + +Submit feedback for developers +------------------------------ + +Do you like py.test? Share some love on Twitter or in your blog posts! + +We'd also like to hear about your propositions and suggestions. Feel free to +submit them as issues `here `__ and: + +* Set the "kind" to "enhancement" or "proposal" so that we can quickly find + about them. +* Explain in detail how they should work. +* Keep the scope as narrow as possible. This will make it easier to implement. +* If you have required skills and/or knowledge, you can always contribute to + these issues! + +Report bugs +----------- + +Report bugs at https://bitbucket.org/hpk42/pytest/issues. + +If you are reporting a bug, please include: + +* Your operating system name and version. +* Any details about your local setup that might be helpful in troubleshooting, + specifically Python interpreter version, + installed libraries and py.test version. +* Detailed steps to reproduce the bug. + +Fix bugs +-------- + +Look through the BitBucket issues for bugs. Here is sample filter you can use: +https://bitbucket.org/hpk42/pytest/issues?status=new&status=open&kind=bug + +:ref:'Talk ' to developers to find out how you can fix specific bugs. + +Implement features +------------------ + +Look through the BitBucket issues for enhancements. Here is sample filter you +can use: +https://bitbucket.org/hpk42/pytest/issues?status=new&status=open&kind=enhancement + +:ref:'Talk ' to developers to find out how you can implement specific +features. + +Write documentation +------------------- + +py.test could always use more documentation. What exactly is needed? + +* More complementary documentation. Have you perhaps found something unclear? +* Documentation translations. We currently have English and Japanese versions. +* Docstrings. There's never too much of them. +* Blog posts, articles and such -- they're all very appreciated. + +Getting started for contributing +================================ + +1. Fork the py.test repository on BitBucket. +.. _checkout: +2. Clone your fork locally:: + + $ hg clone ssh://hg@bitbucket.org/your_name_here/pytest + +3. Install your local copy into a virtualenv. Assuming you have + ``virtualenvwrapper`` (http://virtualenvwrapper.readthedocs.org) installed:: + + $ mkvirtualenv pytest + $ cd pytest/ + $ python setup.py develop + + If that last command complains about not finding the required version + of "py" then you need to use the development pypi repository:: + + $ python setup.py develop -i http://pypi.testrun.org + +4. Create a branch for local development:: + + $ hg branch name-of-your-bugfix-or-feature + + Now you can make your changes locally. + +5. When you're done making changes, check that all of them pass all the tests + (including PEP8 and different Python interpreter versions). It's as simple + as issuing this one command:: + + $ tox + + The least minimum of required Python tests to pass is Python 2.7 and + Python 3.3:: + + $ tox -e py27,py33 + + If you don't seem to have ``tox`` installed, issue this from inside your + virtualenv:: + + $ pip install tox + + You also need to have Python 3.3 and 2.7 available in your system. + +6. Commit your changes and push your branch to BitBucket:: + + $ hg add . + $ hg commit + $ hg push --new-branch -r . + +7. Submit a pull request through the BitBucket website. diff --git a/doc/en/contribute.txt b/doc/en/contribute.txt index f51f55e05..3326d6fb3 100644 --- a/doc/en/contribute.txt +++ b/doc/en/contribute.txt @@ -1,122 +1,3 @@ .. _contributing: -============ -Contributing -============ - -Contributions are highly welcomed and appreciated. Every little help counts, -so do not hesitate! - -Types of contributions -====================== - -Submit feedback for developers ------------------------------- - -Do you like py.test? Share some love on Twitter or in your blog posts! - -We'd also like to hear about your propositions and suggestions. Feel free to -submit them as issues `here `__ and: - -* Set the "kind" to "enhancement" or "proposal" so that we can quickly find - about them. -* Explain in detail how they should work. -* Keep the scope as narrow as possible. This will make it easier to implement. -* If you have required skills and/or knowledge, you can always contribute to - these issues! - -Report bugs ------------ - -Report bugs at https://bitbucket.org/hpk42/pytest/issues. - -If you are reporting a bug, please include: - -* Your operating system name and version. -* Any details about your local setup that might be helpful in troubleshooting, - specifically Python interpreter version, - installed libraries and py.test version. -* Detailed steps to reproduce the bug. - -Fix bugs --------- - -Look through the BitBucket issues for bugs. Here is sample filter you can use: -https://bitbucket.org/hpk42/pytest/issues?status=new&status=open&kind=bug - -:ref:'Talk ' to developers to find out how you can fix specific bugs. - -Implement features ------------------- - -Look through the BitBucket issues for enhancements. Here is sample filter you -can use: -https://bitbucket.org/hpk42/pytest/issues?status=new&status=open&kind=enhancement - -:ref:'Talk ' to developers to find out how you can implement specific -features. - -Write documentation -------------------- - -py.test could always use more documentation. What exactly is needed? - -* More complementary documentation. Have you perhaps found something unclear? -* Documentation translations. We currently have English and Japanese versions. -* Docstrings. There's never too much of them. -* Blog posts, articles and such -- they're all very appreciated. - -Getting started for contributing -================================ - -1. Fork the py.test repository on BitBucket. -.. _checkout: -2. Clone your fork locally:: - - $ hg clone ssh://hg@bitbucket.org/your_name_here/pytest - -3. Install your local copy into a virtualenv. Assuming you have - ``virtualenvwrapper`` (http://virtualenvwrapper.readthedocs.org) installed:: - - $ mkvirtualenv pytest - $ cd pytest/ - $ python setup.py develop - - If that last command complains about not finding the required version - of "py" then you need to use the development pypi repository:: - - $ python setup.py develop -i http://pypi.testrun.org - -4. Create a branch for local development:: - - $ hg branch name-of-your-bugfix-or-feature - - Now you can make your changes locally. - -5. When you're done making changes, check that all of them pass all the tests - (including PEP8 and different Python interpreter versions). It's as simple - as issuing this one command:: - - $ tox - - The least minimum of required Python tests to pass is Python 2.7 and - Python 3.3:: - - $ tox -e py27,py33 - - If you don't seem to have ``tox`` installed, issue this from inside your - virtualenv:: - - $ pip install tox - - You also need to have Python 3.3 and 2.7 available in your system. - -6. Commit your changes and push your branch to BitBucket:: - - $ hg add . - $ hg commit - $ hg push --new-branch -r . - -7. Submit a pull request through the BitBucket website. - -.. include:: links.inc +.. include:: ../../CONTRIBUTING.txt From fbdc6e8cc0b84e338992637e97c7186ce5b8501c Mon Sep 17 00:00:00 2001 From: Piotr Banaszkiewicz Date: Wed, 22 Jan 2014 12:19:33 +0100 Subject: [PATCH 3/4] Addressed contribution guide issues: virtualenv, links, Github mirror, RST rendering --HG-- branch : contributiondocs --- CONTRIBUTING.txt | 68 ++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 54 insertions(+), 14 deletions(-) diff --git a/CONTRIBUTING.txt b/CONTRIBUTING.txt index 6b1e4f206..438ca5558 100644 --- a/CONTRIBUTING.txt +++ b/CONTRIBUTING.txt @@ -43,7 +43,7 @@ Fix bugs Look through the BitBucket issues for bugs. Here is sample filter you can use: https://bitbucket.org/hpk42/pytest/issues?status=new&status=open&kind=bug -:ref:'Talk ' to developers to find out how you can fix specific bugs. +:ref:`Talk ` to developers to find out how you can fix specific bugs. Implement features ------------------ @@ -52,7 +52,7 @@ Look through the BitBucket issues for enhancements. Here is sample filter you can use: https://bitbucket.org/hpk42/pytest/issues?status=new&status=open&kind=enhancement -:ref:'Talk ' to developers to find out how you can implement specific +:ref:`Talk ` to developers to find out how you can implement specific features. Write documentation @@ -68,16 +68,29 @@ py.test could always use more documentation. What exactly is needed? Getting started for contributing ================================ -1. Fork the py.test repository on BitBucket. +The primary development platform for py.test is BitBucket. You can find all +the issues there and submit pull requests. There is, however, +a `GitHub mirror `__ available, too, +although it only allows for submitting pull requests. For a GitHub +contribution guide look :ref:`below `. + +1. Fork the py.test `repository `__ on BitBucket. + +2. Create a local virtualenv (http://www.virtualenv.org/en/latest/):: + + $ virtualenv pytest-venv + $ cd pytest-venv/ + .. _checkout: -2. Clone your fork locally:: + +3. Clone your fork locally:: $ hg clone ssh://hg@bitbucket.org/your_name_here/pytest -3. Install your local copy into a virtualenv. Assuming you have - ``virtualenvwrapper`` (http://virtualenvwrapper.readthedocs.org) installed:: +.. _installing-dev-pytest: + +4. Install your local copy into a virtualenv:: - $ mkvirtualenv pytest $ cd pytest/ $ python setup.py develop @@ -86,11 +99,7 @@ Getting started for contributing $ python setup.py develop -i http://pypi.testrun.org -4. Create a branch for local development:: - - $ hg branch name-of-your-bugfix-or-feature - - Now you can make your changes locally. +.. _testing-pytest: 5. When you're done making changes, check that all of them pass all the tests (including PEP8 and different Python interpreter versions). It's as simple @@ -110,10 +119,41 @@ Getting started for contributing You also need to have Python 3.3 and 2.7 available in your system. -6. Commit your changes and push your branch to BitBucket:: +6. Commit your changes and push to BitBucket:: $ hg add . $ hg commit - $ hg push --new-branch -r . + $ hg push -r . 7. Submit a pull request through the BitBucket website. + + +.. _contribution-on-github: +What about GitHub? +------------------ + +.. warning:: + Remember that GitHub is **not** a default development platform for py.test + and it doesn't include e.g. issue list. + +1. Fork the py.test `repository `__ on GitHub. + +2. Create a local virtualenv (http://www.virtualenv.org/en/latest/):: + + $ virtualenv pytest-venv + $ cd pytest-venv/ + +3. Clone your fork locally:: + + $ git clone git@github.com:your_name_here/pytest.git + +4. :ref:`Install your local copy into a virtualenv ` + and after that :ref:`test your changes `. + +5. Commit your changes and push to GitHub:: + + $ git add . + $ git commit + $ git push -u + +6. Submit a pull request through the GitHub website. From d960fb78fca60d6ec7048d576fab974c3601df8a Mon Sep 17 00:00:00 2001 From: Piotr Banaszkiewicz Date: Wed, 22 Jan 2014 17:05:11 +0100 Subject: [PATCH 4/4] Contribution guide: moved tox inst. instructions up --HG-- branch : contributiondocs --- CONTRIBUTING.txt | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.txt b/CONTRIBUTING.txt index 438ca5558..6b0ed5e45 100644 --- a/CONTRIBUTING.txt +++ b/CONTRIBUTING.txt @@ -102,22 +102,20 @@ contribution guide look :ref:`below `. .. _testing-pytest: 5. When you're done making changes, check that all of them pass all the tests - (including PEP8 and different Python interpreter versions). It's as simple - as issuing this one command:: - - $ tox - - The least minimum of required Python tests to pass is Python 2.7 and - Python 3.3:: - - $ tox -e py27,py33 - - If you don't seem to have ``tox`` installed, issue this from inside your - virtualenv:: + (including PEP8 and different Python interpreter versions). First install + ``tox``:: $ pip install tox - You also need to have Python 3.3 and 2.7 available in your system. + You also need to have Python 2.7 and 3.3 available in your system. Now + running tests is as simple as issuing this one command:: + + $ tox -e py27,py33 + + This command will run tests for both Python 2.7 and 3.3, which is a minimum + required to get your patch merged. To run whole test suit issue:: + + $ tox 6. Commit your changes and push to BitBucket::