How to contribute to Python-Deprecated

Thank you for considering contributing to Python-Deprecated!

Support questions

Please, don’t use the issue tracker for this. Use one of the following resources for questions about your own code:

  • Ask on Stack Overflow. Search with Google first using: site:stackoverflow.com python-deprecated {search term, exception message, etc.}

Reporting issues

  • Describe what you expected to happen.
  • If possible, include a minimal, complete, and verifiable example to help us identify the issue. This also helps check that the issue is not with your own code.
  • Describe what actually happened. Include the full traceback if there was an exception.
  • List your Python, Python-Deprecated versions. If possible, check if this issue is already fixed in the repository.

Submitting patches

  • Include tests if your patch is supposed to solve a bug, and explain clearly under which circumstances the bug happens. Make sure the test fails without your patch.
  • Try to follow PEP8, but you may ignore the line length limit if following it would make the code uglier.

First time setup

  • Download and install the latest version of git.

  • Configure git with your username and email:

    git config --global user.name 'your name'
git config --global user.email 'your email'

  • Make sure you have a GitHub account.

  • Fork Python-Deprecated to your GitHub account by clicking the Fork button.

  • Clone your GitHub fork locally:

    git clone https://github.com/{username}/python-deprecated.git
cd python-deprecated

  • Add the main repository as a remote to update later:

    git remote add vrcmarcos https://github.com/vrcmarcos/python-deprecated.git
git fetch vrcmarcos

  • Create a virtualenv:

    python3 -m venv env
. env/bin/activate
# or "env\Scripts\activate" on Windows

  • Install Python-Deprecated in editable mode with development dependencies:

    pip install -e ".[dev]"

Start coding

  • Create a branch to identify the issue you would like to work on (e.g. 2287-dry-test-suite)
  • Using your favorite editor, make your changes, committing as you go.
  • Try to follow PEP8, but you may ignore the line length limit if following it would make the code uglier.
  • Include tests that cover any code changes you make. Make sure the test fails without your patch. Running the tests.
  • Push your commits to GitHub and create a pull request.
  • Celebrate 🎉

Running the tests

Run the basic test suite with:

pytest tests/

This only runs the tests for the current environment. Whether this is relevant depends on which part of Python-Deprecated you’re working on. Travis-CI will run the full suite when you submit your pull request.

The full test suite takes a long time to run because it tests multiple combinations of Python and dependencies. You need to have Python 2.6, 2.7, 3.3, 3.4, 3.5 3.6, and PyPy 2.7 installed to run all of the environments. Then run:

tox

Running test coverage

Generating a report of lines that do not have test coverage can indicate where to start contributing. Run pytest using coverage and generate a report on the terminal and as an interactive HTML document:

pytest --cov-report term-missing --cov-report html --cov=deprecated tests/
# then open htmlcov/index.html

Read more about coverage.

Running the full test suite with tox will combine the coverage reports from all runs.

make targets

Python-Deprecated provides a Makefile with various shortcuts. They will ensure that all dependencies are installed.

  • make test runs the basic test suite with pytest
  • make cov runs the basic test suite with coverage
  • make test-all runs the full test suite with tox

Generating the documentation

The documentation is automatically generated with ReadTheDocs for each git push on master. You can also generate it manually using Sphinx.

To generate the HTML documentation, run:

sphinx-build -b html docs/source/ dist/docs/html/

To generate the epub v2 documentation, run:

sphinx-build -b epub2 docs/source/ dist/docs/epub/