1Contributing Guidelines 2======================= 3 4So you're interested in contributing to marshmallow or `one of our associated 5projects <https://github.com/marshmallow-code>`__? That's awesome! We 6welcome contributions from anyone willing to work in good faith with 7other contributors and the community (see also our 8:doc:`code_of_conduct`). 9 10Security Contact Information 11---------------------------- 12 13To report a security vulnerability, please use the 14`Tidelift security contact <https://tidelift.com/security>`_. 15Tidelift will coordinate the fix and disclosure. 16 17Questions, Feature Requests, Bug Reports, and Feedback… 18------------------------------------------------------- 19 20…should all be reported on the `Github Issue Tracker`_ . 21 22.. _`Github Issue Tracker`: https://github.com/marshmallow-code/marshmallow/issues?state=open 23 24Ways to Contribute 25------------------ 26 27- Comment on some of marshmallow's `open issues <https://github.com/marshmallow-code/marshmallow/issues>`_ (especially those `labeled "feedback welcome" <https://github.com/marshmallow-code/marshmallow/issues?q=is%3Aopen+is%3Aissue+label%3A%22feedback+welcome%22>`_). Share a solution or workaround. Make a suggestion for how a feature can be made better. Opinions are welcome! 28- Improve `the docs <https://marshmallow.readthedocs.io>`_. 29 For straightforward edits, 30 click the ReadTheDocs menu button in the bottom-right corner of the page and click "Edit". 31 See the :ref:`Documentation <contributing_documentation>` section of this page if you want to build the docs locally. 32- If you think you've found a bug, `open an issue <https://github.com/marshmallow-code/marshmallow/issues>`_. 33- Contribute an :ref:`example usage <contributing_examples>` of marshmallow. 34- Send a PR for an open issue (especially one `labeled "help wanted" <https://github.com/marshmallow-code/marshmallow/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22>`_). The next section details how to contribute code. 35 36 37Contributing Code 38----------------- 39 40Setting Up for Local Development 41++++++++++++++++++++++++++++++++ 42 431. Fork marshmallow_ on Github. 44 45:: 46 47 $ git clone https://github.com/marshmallow-code/marshmallow.git 48 $ cd marshmallow 49 502. Install development requirements. **It is highly recommended that you use a virtualenv.** 51 Use the following command to install an editable version of 52 marshmallow along with its development requirements. 53 54:: 55 56 # After activating your virtualenv 57 $ pip install -e '.[dev]' 58 593. Install the pre-commit hooks, which will format and lint your git staged files. 60 61:: 62 63 # The pre-commit CLI was installed above 64 $ pre-commit install --allow-missing-config 65 66Git Branch Structure 67++++++++++++++++++++ 68 69Marshmallow abides by the following branching model: 70 71``dev`` 72 Current development branch. **New features should branch off here**. 73 74``X.Y-line`` 75 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. 76 77**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. 78 79Pull Requests 80++++++++++++++ 81 821. Create a new local branch. 83 84:: 85 86 # For a new feature 87 $ git checkout -b name-of-feature dev 88 89 # For a bugfix 90 $ git checkout -b fix-something 2.x-line 91 922. Commit your changes. Write `good commit messages <https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html>`_. 93 94:: 95 96 $ git commit -m "Detailed commit message" 97 $ git push origin name-of-feature 98 993. Before submitting a pull request, check the following: 100 101- If the pull request adds functionality, it is tested and the docs are updated. 102- You've added yourself to ``AUTHORS.rst``. 103 1044. Submit a pull request to ``marshmallow-code:dev`` or the appropriate maintenance branch. The `CI <https://dev.azure.com/sloria1/sloria/_build/latest?definitionId=5&branchName=dev>`_ build must be passing before your pull request is merged. 105 106Running tests 107+++++++++++++ 108 109To run all tests: :: 110 111 $ pytest 112 113To run formatting and syntax checks: :: 114 115 $ tox -e lint 116 117(Optional) To run tests in all supported Python versions in their own virtual environments (must have each interpreter installed): :: 118 119 $ tox 120 121.. _contributing_documentation: 122 123Documentation 124+++++++++++++ 125 126Contributions to the documentation are welcome. Documentation is written in `reStructuredText`_ (rST). A quick rST reference can be found `here <https://docutils.sourceforge.io/docs/user/rst/quickref.html>`_. Builds are powered by Sphinx_. 127 128To build the docs in "watch" mode: :: 129 130 $ tox -e watch-docs 131 132Changes in the `docs/` directory will automatically trigger a rebuild. 133 134 135.. _contributing_examples: 136 137Contributing Examples 138+++++++++++++++++++++ 139 140Have a usage example you'd like to share? A custom `Field` that others might find useful? Feel free to add it to the `examples <https://github.com/marshmallow-code/marshmallow/tree/dev/examples>`_ directory and send a pull request. 141 142 143.. _Sphinx: https://www.sphinx-doc.org/ 144.. _`reStructuredText`: https://docutils.sourceforge.io/rst.html 145.. _marshmallow: https://github.com/marshmallow-code/marshmallow 146