Codebase list python-webargs / debian/4.0.0-0kali1 CONTRIBUTING.rst
debian/4.0.0-0kali1

Tree @debian/4.0.0-0kali1 (Download .tar.gz)

CONTRIBUTING.rst @debian/4.0.0-0kali1 — view markup · raw · history · blame

Contributing Guidelines

In General

  • PEP 8, when sensible.
  • Test ruthlessly. Write docs for new features.
  • Even more important than Test-Driven Development--Human-Driven Development.

In Particular

Questions, Feature Requests, Bug Reports, and Feedback. . .

. . .should all be reported on the Github Issue Tracker .

Setting Up for Local Development

  1. Fork webargs on Github.

    $ git clone https://github.com/sloria/webargs.git
$ cd webargs

  2. Install development requirements. It is highly recommended that you use a virtualenv.

    # After activating your virtualenv
$ pip install -r dev-requirements.txt

# If you're using a Python 3 environment
$ pip install -r dev-requirements-py3.txt

  3. (Optional, but recommended) Install the pre-commit hooks, which will format and lint your git staged files.

    # The pre-commit CLI was installed above
$ pre-commit install

Note

webargs uses black for code formatting, which is only compatible with Python>=3.6. Therefore, the pre-commit install command will only work if you have the python3.6 interpreter installed.

Git Branch Structure

Webargs abides by the following branching model:

dev
Current development branch. New features should branch off here.
X.Y-line
Maintenance branch for release X.Y. Bug fixes should be sent to the most recent release branch.. The maintainer will forward-port the fix to dev. Note: exceptions may be made for bug fixes that introduce large code changes.

Always make a new branch for your work, no matter how small. Also, do not put unrelated changes in the same branch or pull request. This makes it more difficult to merge your changes.

Pull Requests

System Message: INFO/1 (<string>, line 66)

Possible title underline, too short for the title. Treating it as ordinary text because it's so short.

1. Create a new local branch.

# For a new feature
$ git checkout -b name-of-feature dev

# For a bugfix
$ git checkout -b fix-something 1.2-line

System Message: INFO/1 (<string>, line 75)

Possible title underline, too short for the title. Treating it as ordinary text because it's so short.

2. Commit your changes. Write good commit messages.

$ git commit -m "Detailed commit message"
$ git push origin name-of-feature
  1. Before submitting a pull request, check the following:

System Message: INFO/1 (<string>, line 2)

Enumerated list start value not ordinal-1: "3" (ordinal 3)
  • If the pull request adds functionality, it is tested and the docs are updated.
  • You've added yourself to AUTHORS.rst.
  1. Submit a pull request to sloria:dev or the appropriate maintenance branch. The Travis CI build must be passing before your pull request is merged.

System Message: INFO/1 (<string>, line 2)

Enumerated list start value not ordinal-1: "4" (ordinal 4)

Running Tests

To run all tests (including syntax checking):

$ invoke test

To run tests without syntax-checking (use this if you don't have the python3.6 interpreter):

$ invoke test --no-syntax

To run tests on Python 2.7, 3.5, 3.6, and 3.7 virtual environments (must have each interpreter installed):

$ tox

Documentation

Contributions to the documentation are welcome. Documentation is written in reStructured Text (rST). A quick rST reference can be found here. Builds are powered by Sphinx.

To install the packages for building the docs:

$ pip install -r docs/requirements.txt

To build the docs:

$ invoke docs -b

The -b (for "browse") automatically opens up the docs in your browser after building.

Contributing Examples

Have a usage example you'd like to share? Feel free to add it to the examples directory and send a pull request.