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