Skip to content

Latest commit

 

History

History
201 lines (150 loc) · 7.92 KB

CONTRIBUTING.rst

File metadata and controls

201 lines (150 loc) · 7.92 KB
Raw

How to contribute

Contributions are welcome! Not familiar with the codebase yet? No problem! There are many ways to contribute to open source projects: reporting bugs, helping with the documentation, spreading the word and of course, adding new features and patches.

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 eve {search term, exception message, etc.}
  • The mailing list is intended to be a low traffic resource for both developers/contributors and API maintainers looking for help or requesting feedback.
  • The IRC channel #python-eve on FreeNode.

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 and Eve 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.
  • Enable and install pre-commit to ensure styleguides and codechecks are followed. CI will reject a change that does not conform to the guidelines.

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 Eve to your GitHub account by clicking the Fork button.

  • Clone your GitHub fork locally:

    git clone https://github.com/{username}/eve
cd eve

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

    git remote add pyeve https://github.com/pyeve/eve
git fetch pyeve

  • Create a virtualenv:

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

  • Install Eve in editable mode with development dependencies:

    pip install -e ".[dev]"

  • Install pre-commit and then activate its hooks. pre-commit is a framework for managing and maintaining multi-language pre-commit hooks. Eve uses pre-commit to ensure code-style and code formatting is the same:

    $ pip install --user pre-commit
$ pre-commit install

    Afterwards, pre-commit will run whenever you commit.

Start coding

  • Create a branch to identify the issue you would like to work on (e.g. fix_for_#1280)
  • Using your favorite editor, make your changes, committing as you go.
  • Follow PEP8.
  • Include tests that cover any code changes you make. Make sure the test fails without your patch. Run the tests..
  • Push your commits to GitHub and create a pull request.
  • Celebrate 🎉

Running the tests

You should have Python 3.9+ available in your system. Now running tests is as simple as issuing this command:

$ tox -e linting,py310,py39

This command will run tests via the "tox" tool against Python 3.10 and 3.9 and also perform "lint" coding-style checks.

You can pass different options to tox. For example, to run tests on Python 3.10 and pass options to pytest (e.g. enter pdb on failure) to pytest you can do:

$ tox -e py310 -- --pdb

Or to only run tests in a particular test module on Python 3.6:

$ tox -e py310 -- -k TestGet

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 3.9, 3.10, 3.11, 3.12 and PyPy installed to run all of the environments. Then run:

tox

Please note that you need an active MongoDB instance running on localhost in order for the tests run. Save yourself some time and headache by creating a MongoDB user with the password defined in the test_settings.py file in the admin database (the pre-commit process is unforgiving if you don't want to commit your admin credentials but still have the file modified, which would be necessary for tox). If you want to run a local MongoDB instance along with an SSH tunnel to a remote instance, if you can, have the local use the default port and the remote use some other port. If you can't, fixing the tests that won't play nicely is probably more trouble than connecting to the remote and local instances one at a time. Also, be advised that in order to execute the :ref:`ratelimiting` tests you need a running Redis server. The Rate-Limiting tests are silently skipped if any of the two conditions are not met.

Building the docs

Build the docs in the docs directory using Sphinx:

cd docs
make html

Open _build/html/index.html in your browser to view the docs.

Read more about Sphinx.

make targets

Eve provides a Makefile with various shortcuts. They will ensure that all dependencies are installed.

  • make test runs the basic test suite with pytest
  • make test-all runs the full test suite with tox
  • make docs builds the HTML documentation
  • make check performs some checks on the package
  • make install-dev install Eve in editable mode with all development dependencies.

First time contributor?

It's alright. We've all been there. See next chapter.

Don't know where to start?

There are usually several TODO comments scattered around the codebase, maybe check them out and see if you have ideas, or can help with them. Also, check the open issues in case there's something that sparks your interest. And what about documentation? I suck at English, so if you're fluent with it (or notice any typo and/or mistake), why not help with that? In any case, other than GitHub help pages, you might want to check this excellent Effective Guide to Pull Requests