IRIS YANG | 3121357 | 2020-08-18 13:17:02 +0000 | [diff] [blame] | 1 | How to contribute to Jinja |
| 2 | ========================== |
| 3 | |
| 4 | Thank you for considering contributing to Jinja! |
| 5 | |
| 6 | |
| 7 | Support questions |
| 8 | ----------------- |
| 9 | |
| 10 | Please, don't use the issue tracker for this. The issue tracker is a |
| 11 | tool to address bugs and feature requests in Jinja itself. Use one of |
| 12 | the following resources for questions about using Jinja or issues with |
| 13 | your 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 | |
| 25 | Reporting issues |
| 26 | ---------------- |
| 27 | |
| 28 | Include 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 | |
| 43 | Submitting patches |
| 44 | ------------------ |
| 45 | |
| 46 | If there is not an open issue for what you want to submit, prefer |
| 47 | opening one for discussion before working on a PR. You can work on any |
| 48 | issue that doesn't have an open PR linked to it or a maintainer assigned |
| 49 | to it. These show up in the sidebar. No need to ask if you can work on |
| 50 | an issue that interests you. |
| 51 | |
| 52 | Include 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 | |
| 69 | First 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 | |
| 130 | Start 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 | |
| 166 | Running the tests |
| 167 | ~~~~~~~~~~~~~~~~~ |
| 168 | |
| 169 | Run the basic test suite with pytest. |
| 170 | |
| 171 | .. code-block:: text |
| 172 | |
| 173 | $ pytest |
| 174 | |
| 175 | This runs the tests for the current environment, which is usually |
| 176 | sufficient. CI will run the full suite when you submit your pull |
| 177 | request. You can run the full test suite with tox if you don't want to |
| 178 | wait. |
| 179 | |
| 180 | .. code-block:: text |
| 181 | |
| 182 | $ tox |
| 183 | |
| 184 | |
| 185 | Running test coverage |
| 186 | ~~~~~~~~~~~~~~~~~~~~~ |
| 187 | |
| 188 | Generating a report of lines that do not have test coverage can indicate |
| 189 | where to start contributing. Run ``pytest`` using ``coverage`` and |
| 190 | generate a report. |
| 191 | |
| 192 | .. code-block:: text |
| 193 | |
| 194 | $ pip install coverage |
| 195 | $ coverage run -m pytest |
| 196 | $ coverage html |
| 197 | |
| 198 | Open ``htmlcov/index.html`` in your browser to explore the report. |
| 199 | |
| 200 | Read more about `coverage <https://coverage.readthedocs.io>`__. |
| 201 | |
| 202 | |
| 203 | Building the docs |
| 204 | ~~~~~~~~~~~~~~~~~ |
| 205 | |
| 206 | Build the docs in the ``docs`` directory using Sphinx. |
| 207 | |
| 208 | .. code-block:: text |
| 209 | |
| 210 | $ cd docs |
| 211 | $ make html |
| 212 | |
| 213 | Open ``_build/html/index.html`` in your browser to view the docs. |
| 214 | |
| 215 | Read more about `Sphinx <https://www.sphinx-doc.org/en/stable/>`__. |