| commit | author | age | ||
| e5d98c | 1 | Contributing |
| SP | 2 | ============ |
| 3 | ||
| 4 | All projects under the Pylons Projects, including this one, follow the | |
| 5 | guidelines established at [How to | |
| 6 | Contribute](http://www.pylonsproject.org/community/how-to-contribute) and | |
| 7 | [Coding Style and | |
| 8 | Standards](http://docs.pylonsproject.org/en/latest/community/codestyle.html). | |
| 9 | ||
| 10 | You can contribute to this project in several ways. | |
| 11 | ||
| 12 | * [File an Issue on GitHub](https://github.com/Pylons/pyramid/issues) | |
| 13 | * Fork this project and create a branch with your suggested change. When ready, | |
| 14 | submit a pull request for consideration. [GitHub | |
| 15 | Flow](https://guides.github.com/introduction/flow/index.html) describes the | |
| 16 | workflow process and why it's a good practice. When submitting a pull | |
| 17 | request, sign | |
| 18 | [CONTRIBUTORS.txt](https://github.com/Pylons/pyramid/blob/master/CONTRIBUTORS.txt) | |
| 19 | if you have not yet done so. | |
| 20 | * Join the IRC channel #pyramid on irc.freenode.net. | |
| 21 | ||
| 22 | Git Branches | |
| 23 | ------------ | |
| 24 | Git branches and their purpose and status at the time of this writing are | |
| 25 | listed below. | |
| 26 | ||
| 27 | * [master](https://github.com/Pylons/pyramid/) - The branch on which further | |
| 28 | development takes place. The default branch on GitHub. | |
| 29 | * [1.6-branch](https://github.com/Pylons/pyramid/tree/1.6-branch) - The branch | |
| 30 | to which further development on master should be backported. This is also a | |
| 31 | development branch. | |
| 32 | * [1.5-branch](https://github.com/Pylons/pyramid/tree/1.5-branch) - The branch | |
| 33 | classified as "stable" or "latest". Actively maintained. | |
| 34 | * [1.4-branch](https://github.com/Pylons/pyramid/tree/1.4-branch) - The oldest | |
| 35 | actively maintained and stable branch. | |
| 36 | ||
| 37 | Older branches are not actively maintained. In general, two stable branches and | |
| 38 | one or two development branches are actively maintained. | |
| 39 | ||
| 40 | Prerequisites | |
| 41 | ------------- | |
| 42 | ||
| 43 | Follow the instructions in HACKING.txt for your version or branch located in | |
| 44 | the [root of the Pyramid repository](https://github.com/Pylons/pyramid/) to | |
| 45 | install Pyramid and the tools needed to run its tests and build its | |
| 46 | documentation. | |
| 47 | ||
| 48 | Building documentation for a Pylons Project project | |
| 49 | --------------------------------------------------- | |
| 50 | ||
| 51 | *Note:* These instructions might not work for Windows users. Suggestions to | |
| 52 | improve the process for Windows users are welcome by submitting an issue or a | |
| 53 | pull request. Windows users may find it helpful to follow the guide [Installing | |
| 54 | Pyramid on a Windows | |
| 55 | System](http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/install.html#installing-pyramid-on-a-windows-system). | |
| 56 | ||
| 57 | 1. Fork the repo on GitHub by clicking the [Fork] button. | |
| 58 | 2. Clone your fork into a workspace on your local machine. | |
| 59 | ||
| 60 | git clone git@github.com:<username>/pyramid.git | |
| 61 | ||
| 62 | 3. Add a git remote "upstream" for the cloned fork. | |
| 63 | ||
| 64 | git remote add upstream git@github.com:Pylons/pyramid.git | |
| 65 | ||
| 66 | 4. Set an environment variable as instructed in the | |
| 67 | [prerequisites](https://github.com/Pylons/pyramid/blob/master/HACKING.txt#L55-L58). | |
| 68 | ||
| 69 | # Mac and Linux | |
| 70 | $ export VENV=~/hack-on-pyramid/env | |
| 71 | ||
| 72 | # Windows | |
| 73 | set VENV=c:\hack-on-pyramid\env | |
| 74 | ||
| 75 | 5. Try to build the docs in your workspace. | |
| 76 | ||
| 77 | # Mac and Linux | |
| 78 | $ make clean html SPHINXBUILD=$VENV/bin/sphinx-build | |
| 79 | ||
| 80 | # Windows | |
| 81 | c:\> make clean html SPHINXBUILD=%VENV%\bin\sphinx-build | |
| 82 | ||
| 83 | If successful, then you can make changes to the documentation. You can | |
| 84 | load the built documentation in the `/_build/html/` directory in a web | |
| 85 | browser. | |
| 86 | ||
| 87 | 6. From this point forward, follow the typical [git | |
| 88 | workflow](https://help.github.com/articles/what-is-a-good-git-workflow/). | |
| 89 | Start by pulling from the upstream to get the most current changes. | |
| 90 | ||
| 91 | git pull upstream master | |
| 92 | ||
| 93 | 7. Make a branch, make changes to the docs, and rebuild them as indicated in | |
| 94 | step 5. To speed up the build process, you can omit `clean` from the above | |
| 95 | command to rebuild only those pages that depend on the files you have | |
| 96 | changed. | |
| 97 | ||
| 98 | 8. Once you are satisfied with your changes and the documentation builds | |
| 99 | successfully without errors or warnings, then git commit and push them to | |
| 100 | your "origin" repository on GitHub. | |
| 101 | ||
| 102 | git commit -m "commit message" | |
| 103 | git push -u origin --all # first time only, subsequent can be just 'git push'. | |
| 104 | ||
| 105 | 9. Create a [pull request](https://help.github.com/articles/using-pull-requests/). | |
| 106 | ||
| 107 | 10. Repeat the process starting from Step 6. | |
