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