Codebase list apispec / master CONTRIBUTING.rst
master

Tree @master (Download .tar.gz)

CONTRIBUTING.rst @master — view markup · raw · history · blame

Contributing Guidelines

Security Contact Information

To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure.

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

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

Contributing Code

Setting Up for Local Development

  1. Fork apispec on GitHub.
$ git clone https://github.com/marshmallow-code/apispec.git
$ cd apispec
  1. Install development requirements. It is highly recommended that you use a virtualenv. Use the following command to install an editable version of apispec along with its development requirements.

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

Enumerated list start value not ordinal-1: "2" (ordinal 2)
# After activating your virtualenv
$ pip install -e '.[dev]'
  1. Install the pre-commit hooks, which will format and lint your git staged files.

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

Enumerated list start value not ordinal-1: "3" (ordinal 3)
# The pre-commit CLI was installed above
$ pre-commit install

Git Branch Structure

apispec 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

  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
  1. Commit your changes. Write good commit messages.

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

Enumerated list start value not ordinal-1: "2" (ordinal 2)
$ 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 marshmallow-code:dev or the appropriate maintenance branch.
    The 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:

$ pytest

To run syntax checks:

$ tox -e lint

(Optional) To run tests in all supported Python versions in their own virtual environments (must have each interpreter installed):

$ tox

Documentation

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

To build the docs in "watch" mode:

$ tox -e watch-docs

Changes in the docs/ directory will automatically trigger a rebuild.