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 |
612672
|
54 |
[prerequisites](https://github.com/Pylons/pyramid/blob/master/HACKING.txt#L48-L56). |
3a8c85
|
55 |
|
SP |
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. |