1How to contribute to Jinja 2========================== 3 4Thank you for considering contributing to Jinja! 5 6 7Support questions 8----------------- 9 10Please, don't use the issue tracker for this. The issue tracker is a 11tool to address bugs and feature requests in Jinja itself. Use one of 12the following resources for questions about using Jinja or issues with 13your own code: 14 15- The ``#get-help`` channel on our Discord chat: 16 https://discord.gg/t6rrQZH 17- The mailing list flask@python.org for long term discussion or larger 18 issues. 19- Ask on `Stack Overflow`_. Search with Google first using: 20 ``site:stackoverflow.com jinja {search term, exception message, etc.}`` 21 22.. _Stack Overflow: https://stackoverflow.com/questions/tagged/jinja?sort=linked 23 24 25Reporting issues 26---------------- 27 28Include the following information in your post: 29 30- Describe what you expected to happen. 31- If possible, include a `minimal reproducible example`_ to help us 32 identify the issue. This also helps check that the issue is not with 33 your own code. 34- Describe what actually happened. Include the full traceback if there 35 was an exception. 36- List your Python and Jinja versions. If possible, check if this 37 issue is already fixed in the latest releases or the latest code in 38 the repository. 39 40.. _minimal reproducible example: https://stackoverflow.com/help/minimal-reproducible-example 41 42 43Submitting patches 44------------------ 45 46If there is not an open issue for what you want to submit, prefer 47opening one for discussion before working on a PR. You can work on any 48issue that doesn't have an open PR linked to it or a maintainer assigned 49to it. These show up in the sidebar. No need to ask if you can work on 50an issue that interests you. 51 52Include the following in your patch: 53 54- Use `Black`_ to format your code. This and other tools will run 55 automatically if you install `pre-commit`_ using the instructions 56 below. 57- Include tests if your patch adds or changes code. Make sure the test 58 fails without your patch. 59- Update any relevant docs pages and docstrings. Docs pages and 60 docstrings should be wrapped at 72 characters. 61- Add an entry in ``CHANGES.rst``. Use the same style as other 62 entries. Also include ``.. versionchanged::`` inline changelogs in 63 relevant docstrings. 64 65.. _Black: https://black.readthedocs.io 66.. _pre-commit: https://pre-commit.com 67 68 69First time setup 70~~~~~~~~~~~~~~~~ 71 72- Download and install the `latest version of git`_. 73- Configure git with your `username`_ and `email`_. 74 75 .. code-block:: text 76 77 $ git config --global user.name 'your name' 78 $ git config --global user.email 'your email' 79 80- Make sure you have a `GitHub account`_. 81- Fork Jinja to your GitHub account by clicking the `Fork`_ button. 82- `Clone`_ the main repository locally. 83 84 .. code-block:: text 85 86 $ git clone https://github.com/pallets/jinja 87 $ cd jinja 88 89- Add your fork as a remote to push your work to. Replace 90 ``{username}`` with your username. This names the remote "fork", the 91 default Pallets remote is "origin". 92 93 .. code-block:: text 94 95 git remote add fork https://github.com/{username}/jinja 96 97- Create a virtualenv. 98 99 .. code-block:: text 100 101 $ python3 -m venv env 102 $ . env/bin/activate 103 104 On Windows, activating is different. 105 106 .. code-block:: text 107 108 > env\Scripts\activate 109 110- Install Jinja in editable mode with development dependencies. 111 112 .. code-block:: text 113 114 $ pip install -e . -r requirements/dev.txt 115 116- Install the pre-commit hooks. 117 118 .. code-block:: text 119 120 $ pre-commit install 121 122.. _latest version of git: https://git-scm.com/downloads 123.. _username: https://help.github.com/en/articles/setting-your-username-in-git 124.. _email: https://help.github.com/en/articles/setting-your-commit-email-address-in-git 125.. _GitHub account: https://github.com/join 126.. _Fork: https://github.com/pallets/jinja/fork 127.. _Clone: https://help.github.com/en/articles/fork-a-repo#step-2-create-a-local-clone-of-your-fork 128 129 130Start coding 131~~~~~~~~~~~~ 132 133- Create a branch to identify the issue you would like to work on. If 134 you're submitting a bug or documentation fix, branch off of the 135 latest ".x" branch. 136 137 .. code-block:: text 138 139 $ git fetch origin 140 $ git checkout -b your-branch-name origin/1.1.x 141 142 If you're submitting a feature addition or change, branch off of the 143 "master" branch. 144 145 .. code-block:: text 146 147 $ git fetch origin 148 $ git checkout -b your-branch-name origin/master 149 150- Using your favorite editor, make your changes, 151 `committing as you go`_. 152- Include tests that cover any code changes you make. Make sure the 153 test fails without your patch. Run the tests as described below. 154- Push your commits to your fork on GitHub and 155 `create a pull request`_. Link to the issue being addressed with 156 ``fixes #123`` in the pull request. 157 158 .. code-block:: text 159 160 $ git push --set-upstream fork your-branch-name 161 162.. _committing as you go: https://dont-be-afraid-to-commit.readthedocs.io/en/latest/git/commandlinegit.html#commit-your-changes 163.. _create a pull request: https://help.github.com/en/articles/creating-a-pull-request 164 165 166Running the tests 167~~~~~~~~~~~~~~~~~ 168 169Run the basic test suite with pytest. 170 171.. code-block:: text 172 173 $ pytest 174 175This runs the tests for the current environment, which is usually 176sufficient. CI will run the full suite when you submit your pull 177request. You can run the full test suite with tox if you don't want to 178wait. 179 180.. code-block:: text 181 182 $ tox 183 184 185Running test coverage 186~~~~~~~~~~~~~~~~~~~~~ 187 188Generating a report of lines that do not have test coverage can indicate 189where to start contributing. Run ``pytest`` using ``coverage`` and 190generate a report. 191 192.. code-block:: text 193 194 $ pip install coverage 195 $ coverage run -m pytest 196 $ coverage html 197 198Open ``htmlcov/index.html`` in your browser to explore the report. 199 200Read more about `coverage <https://coverage.readthedocs.io>`__. 201 202 203Building the docs 204~~~~~~~~~~~~~~~~~ 205 206Build the docs in the ``docs`` directory using Sphinx. 207 208.. code-block:: text 209 210 $ cd docs 211 $ make html 212 213Open ``_build/html/index.html`` in your browser to view the docs. 214 215Read more about `Sphinx <https://www.sphinx-doc.org/en/stable/>`__. 216