| commit | author | age | ||
| 456d0f | 1 | # Contributing |
| 3a8c85 | 2 | |
| 456d0f | 3 | All projects under the Pylons Projects, including this one, follow the guidelines established at [How to Contribute](https://pylonsproject.org/community-how-to-contribute.html), [Coding Style and Standards](https://pylonsproject.org/community-coding-style-standards.html), and [Pylons Project Documentation Style Guide](https://docs.pylonsproject.org/projects/docs-style-guide/). |
| 3a8c85 | 4 | |
| SP | 5 | You can contribute to this project in several ways. |
| 6 | ||
| 7 | * [File an Issue on GitHub](https://github.com/Pylons/pyramid/issues) | |
| 456d0f | 8 | * Fork this project and create a branch with your suggested change. When ready, submit a pull request for consideration. [GitHub Flow](https://guides.github.com/introduction/flow/index.html) describes the workflow process and why it's a good practice. When submitting a pull request, sign [CONTRIBUTORS.txt](https://github.com/Pylons/pyramid/blob/master/CONTRIBUTORS.txt) if you have not yet done so. |
| SP | 9 | * Join the [IRC channel #pyramid on irc.freenode.net](https://webchat.freenode.net/?channels=pyramid). |
| 44d930 | 10 | |
| 456d0f | 11 | ## Git Branches |
| SP | 12 | |
| 13 | Git branches and their purpose and status at the time of this writing are listed below. | |
| 44d930 | 14 | |
| SP | 15 | * [master](https://github.com/Pylons/pyramid/) - The branch on which further |
| 6d42e2 | 16 | development takes place. The default branch on GitHub. |
| 156c7f | 17 | * [1.9-branch](https://github.com/Pylons/pyramid/tree/1.9-branch) - The branch |
| 6d42e2 | 18 | classified as "stable" or "latest". |
| 884eb5 | 19 | * [1.8-branch](https://github.com/Pylons/pyramid/tree/1.8-branch) - The oldest |
| 6d42e2 | 20 | actively maintained and stable branch. |
| 44d930 | 21 | |
| SP | 22 | Older branches are not actively maintained. In general, two stable branches and |
| 23 | one or two development branches are actively maintained. | |
| 3a8c85 | 24 | |
| 456d0f | 25 | ## Prerequisites |
| 3a8c85 | 26 | |
| SP | 27 | Follow the instructions in HACKING.txt for your version or branch located in |
| 28 | the [root of the Pyramid repository](https://github.com/Pylons/pyramid/) to | |
| 29 | install Pyramid and the tools needed to run its tests and build its | |
| 30 | documentation. | |
| 31 | ||
| 456d0f | 32 | ## Building documentation for a Pylons Project project |
| 3a8c85 | 33 | |
| SP | 34 | *Note:* These instructions might not work for Windows users. Suggestions to |
| 35 | improve the process for Windows users are welcome by submitting an issue or a | |
| 36 | pull request. Windows users may find it helpful to follow the guide [Installing | |
| 37 | Pyramid on a Windows | |
| 19d341 | 38 | System](https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/install.html#installing-pyramid-on-a-windows-system). |
| 3a8c85 | 39 | |
| SP | 40 | 1. Fork the repo on GitHub by clicking the [Fork] button. |
| 41 | 2. Clone your fork into a workspace on your local machine. | |
| 42 | ||
| 44d930 | 43 | git clone git@github.com:<username>/pyramid.git |
| 3a8c85 | 44 | |
| aaca33 | 45 | 3. Change directories into the cloned repository |
| 96a62f | 46 | |
| C | 47 | cd pyramid |
| 48 | ||
| aaca33 | 49 | 4. Add a git remote "upstream" for the cloned fork. |
| 3a8c85 | 50 | |
| SP | 51 | git remote add upstream git@github.com:Pylons/pyramid.git |
| 52 | ||
| aaca33 | 53 | 5. Create a virtual environment and set an environment variable as instructed in the |
| 3a8c85 | 54 | [prerequisites](https://github.com/Pylons/pyramid/blob/master/HACKING.txt#L55-L58). |
| SP | 55 | |
| 56 | # Mac and Linux | |
| 57 | $ export VENV=~/hack-on-pyramid/env | |
| 58 | ||
| 59 | # Windows | |
| 60 | set VENV=c:\hack-on-pyramid\env | |
| 61 | ||
| aaca33 | 62 | 6. Install `tox` into your virtual environment. |
| 96a62f | 63 | |
| C | 64 | $ $VENV/bin/pip install tox |
| 65 | ||
| aaca33 | 66 | 7. Try to build the docs in your workspace. |
| 3a8c85 | 67 | |
| 96a62f | 68 | $ $VENV/bin/tox -e docs |
| 3a8c85 | 69 | |
| 96a62f | 70 | When the build finishes, you'll find HTML documentation rendered in |
| C | 71 | `.tox/docs/html`. An `epub` version will be in `.tox/docs/epub`. And the |
| 72 | result of the tests that are run on the documentation will be in | |
| 73 | `.tox/docs/doctest`. | |
| 3a8c85 | 74 | |
| aaca33 | 75 | 8. From this point forward, follow the typical [git |
| 44d930 | 76 | workflow](https://help.github.com/articles/what-is-a-good-git-workflow/). |
| 96a62f | 77 | *Always* start by pulling from the upstream to get the most current changes. |
| 3a8c85 | 78 | |
| SP | 79 | git pull upstream master |
| 80 | ||
| aaca33 | 81 | 9. Make a branch, make changes to the docs, and rebuild them as indicated above. |
| 3a8c85 | 82 | |
| aaca33 | 83 | 10. Once you are satisfied with your changes and the documentation builds |
| SP | 84 | successfully without errors or warnings, then git commit and push them to |
| 85 | your "origin" repository on GitHub. | |
| 3a8c85 | 86 | |
| SP | 87 | git commit -m "commit message" |
| 88 | git push -u origin --all # first time only, subsequent can be just 'git push'. | |
| 89 | ||
| aaca33 | 90 | 11. Create a [pull request](https://help.github.com/articles/using-pull-requests/). |
| 3a8c85 | 91 | |
| aaca33 | 92 | 12. Repeat the process starting from Step 8. |
