So you're interested in contributing to marshmallow or one of our associated projects? That's awesome! We welcome contributions from anyone willing to work in good faith with other contributors and the community (see also our :ref:`code-of-conduct`).
…should all be reported on the Github Issue Tracker .
- Comment on some of marshmallow's open issues (especially those labeled "feedback welcome"). Share a solution or workaround. Make a suggestion for how a feature can be made better. Opinions are welcome!
- Improve the docs. For straightforward edits, click the ReadTheDocs menu button in the bottom-right corner of the page and click "Edit". See the :ref:`Documentation <contributing_documentation>` section of this page if you want to build the docs locally.
- If you think you've found a bug, open an issue.
- Contribute an :ref:`example usage <contributing_examples>` of marshmallow.
- Send a PR for an open issue (especially one labeled "please help"). The next section details how to contribute code.
- PEP 8, when sensible.
- Test ruthlessly. Write docs for new features.
- Even more important than Test-Driven Development--Human-Driven Development.
Fork marshmallow on Github.
$ git clone https://github.com/marshmallow-code/marshmallow.git $ cd marshmallow
Install development requirements. It is highly recommended that you use a virtualenv.
# After activating your virtualenv $ pip install -r dev-requirements.txt
Install marshmallow in develop mode.
$ pip install -e .
Marshmallow abides by the following branching model:
dev- Current development branch. New features should branch off here.
pypi- Current production release on PyPI.
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 todev. 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.
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 2.x-line
2. Commit your changes. Write good commit messages.
$ git commit -m "Detailed commit message" $ git push origin name-of-feature
- Before submitting a pull request, check the following:
- If the pull request adds functionality, it is tested and the docs are updated.
- You've added yourself to
AUTHORS.rst.
- Submit a pull request to
marshmallow-code:devor the appropriate maintenance branch. The Travis CI build must be passing before your pull request is merged.
To run all tests:
$ invoke test
To run tests on Python 2.7, 3.4, 3.5, and PyPy virtual environments (must have each interpreter installed):
$ tox
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, run the following in the root of the project:
$ 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.
You can also build the docs in "watch" mode:
$ pip install sphinx-autobuild $ invoke docs -wb
Changes in the docs/ directory will automatically trigger a rebuild.
Have a usage example you'd like to share? A custom Field that others might find useful? Feel free to add it to the examples directory and send a pull request.