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/pallets 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?tab=Frequent 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- Upgrade pip and setuptools. 111 112 .. code-block:: text 113 114 $ python -m pip install --upgrade pip setuptools 115 116- Install the development dependencies, then install Jinja in editable 117 mode. 118 119 .. code-block:: text 120 121 $ pip install -r requirements/dev.txt && pip install -e . 122 123- Install the pre-commit hooks. 124 125 .. code-block:: text 126 127 $ pre-commit install 128 129.. _latest version of git: https://git-scm.com/downloads 130.. _username: https://docs.github.com/en/github/using-git/setting-your-username-in-git 131.. _email: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address 132.. _GitHub account: https://github.com/join 133.. _Fork: https://github.com/pallets/jinja/fork 134.. _Clone: https://docs.github.com/en/github/getting-started-with-github/fork-a-repo#step-2-create-a-local-clone-of-your-fork 135 136 137Start coding 138~~~~~~~~~~~~ 139 140- Create a branch to identify the issue you would like to work on. If 141 you're submitting a bug or documentation fix, branch off of the 142 latest ".x" branch. 143 144 .. code-block:: text 145 146 $ git fetch origin 147 $ git checkout -b your-branch-name origin/3.0.x 148 149 If you're submitting a feature addition or change, branch off of the 150 "main" branch. 151 152 .. code-block:: text 153 154 $ git fetch origin 155 $ git checkout -b your-branch-name origin/main 156 157- Using your favorite editor, make your changes, 158 `committing as you go`_. 159- Include tests that cover any code changes you make. Make sure the 160 test fails without your patch. Run the tests as described below. 161- Push your commits to your fork on GitHub and 162 `create a pull request`_. Link to the issue being addressed with 163 ``fixes #123`` in the pull request. 164 165 .. code-block:: text 166 167 $ git push --set-upstream fork your-branch-name 168 169.. _committing as you go: https://dont-be-afraid-to-commit.readthedocs.io/en/latest/git/commandlinegit.html#commit-your-changes 170.. _create a pull request: https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request 171 172 173Running the tests 174~~~~~~~~~~~~~~~~~ 175 176Run the basic test suite with pytest. 177 178.. code-block:: text 179 180 $ pytest 181 182This runs the tests for the current environment, which is usually 183sufficient. CI will run the full suite when you submit your pull 184request. You can run the full test suite with tox if you don't want to 185wait. 186 187.. code-block:: text 188 189 $ tox 190 191 192Running test coverage 193~~~~~~~~~~~~~~~~~~~~~ 194 195Generating a report of lines that do not have test coverage can indicate 196where to start contributing. Run ``pytest`` using ``coverage`` and 197generate a report. 198 199.. code-block:: text 200 201 $ pip install coverage 202 $ coverage run -m pytest 203 $ coverage html 204 205Open ``htmlcov/index.html`` in your browser to explore the report. 206 207Read more about `coverage <https://coverage.readthedocs.io>`__. 208 209 210Building the docs 211~~~~~~~~~~~~~~~~~ 212 213Build the docs in the ``docs`` directory using Sphinx. 214 215.. code-block:: text 216 217 $ cd docs 218 $ make html 219 220Open ``_build/html/index.html`` in your browser to view the docs. 221 222Read more about `Sphinx <https://www.sphinx-doc.org/en/stable/>`__. 223