Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
Browse the repository at this point in the history
add contributing.md
- Loading branch information
1 parent
68c8f94
commit 4c084fa
Showing
2 changed files
with
78 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,9 +1,15 @@ | ||
Pyramid Tutorials | ||
================= | ||
|
||
A `listing of tutorials | ||
A `listing of community contributed tutorials | ||
<http://docs.pylonsproject.org/projects/pyramid-tutorials/en/latest/>`_ for | ||
Pyramid. | ||
|
||
Read `documentation of the Pyramid web application framework | ||
<http://docs.pylonsproject.org/projects/pyramid/en/latest/>`_. | ||
|
||
How to contribute | ||
----------------- | ||
|
||
See `contributing.md | ||
<https://github.com/Pylons/pyramid_tutorials/blob/master/contributing.md>`_. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,71 @@ | ||
Contributing | ||
============ | ||
|
||
All projects under the Pylons Projects, including this one, follow the guidelines established at [How to Contribute](http://www.pylonsproject.org/community/how-to-contribute). | ||
|
||
You can contribute to this project in several ways. | ||
|
||
* [File an Issue on GitHub](https://github.com/Pylons/pyramid_tutorials/issues) | ||
* 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_tutorials/blob/master/CONTRIBUTORS.txt) if you have not yet done so. | ||
* Join the IRC channel #pyramid on irc.freenode.net. | ||
|
||
Prerequisites | ||
------------- | ||
|
||
Follow the instructions to install Pyramid and the tools needed to build its documentation in [HACKING.txt](https://github.com/Pylons/pyramid/blob/master/HACKING.txt). We will leverage this virtual environment and the tools installed there to build documentation for this project. This has several advantages: | ||
|
||
* You don't have to install Sphinx and its dependencies another time. | ||
* You are encouraged to contribute to the official tutorials in the Pyramid documentation. | ||
* [Quick Tutorial for Pyramid](http://docs.pylonsproject.org/projects/pyramid/en/latest/quick_tutorial/index.html) | ||
* [Creating Your First Pyramid Application](http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/firstapp.html) | ||
* [SQLAlchemy + URL Dispatch Wiki Tutorial](http://docs.pylonsproject.org/projects/pyramid/en/latest/tutorials/wiki2/index.html) | ||
* [ZODB + Traversal Wiki Tutorial](http://docs.pylonsproject.org/projects/pyramid/en/latest/tutorials/wiki/index.html) | ||
* [Running a Pyramid Application under mod_wsgi](http://docs.pylonsproject.org/projects/pyramid/en/latest/tutorials/modwsgi/index.html) | ||
* No increased maintenance for the Pylons Project. | ||
|
||
Building documentation for a Pylons Project project | ||
--------------------------------------------------- | ||
|
||
*Note:* These instructions might not work for Windows users. Suggestions to improve the process for Windows users are welcome by submitting an issue or a pull request. Windows users may find it helpful to follow the guide [Installing Pyramid on a Windows System](http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/install.html#installing-pyramid-on-a-windows-system). | ||
|
||
1. Fork the repo on GitHub by clicking the [Fork] button. | ||
2. Clone your fork into a workspace on your local machine. | ||
|
||
git@github.com:<username>/pyramid_tutorials.git | ||
|
||
3. Add a git remote "upstream" for the cloned fork. | ||
|
||
git remote add upstream git@github.com:Pylons/pyramid_tutorials.git | ||
|
||
4. Set an environment variable as instructed in the [prerequisites](https://github.com/Pylons/pyramid/blob/master/HACKING.txt#L55-L58). | ||
|
||
# Mac and Linux | ||
$ export VENV=~/hack-on-pyramid/env | ||
|
||
# Windows | ||
set VENV=c:\hack-on-pyramid\env | ||
|
||
5. Try to build the docs in your workspace. | ||
|
||
# Mac and Linux | ||
$ make clean html SPHINXBUILD=$VENV/bin/sphinx-build | ||
|
||
# Windows | ||
c:\> make clean html SPHINXBUILD=%VENV%\bin\sphinx-build | ||
|
||
If successful, then you can make changes to the documentation. You can load the built documentation in the `/_build/html/` directory in a web browser. | ||
|
||
6. From this point forward, follow the typical git workflow. Start by pulling from the upstream to get the most current changes. | ||
|
||
git pull upstream master | ||
|
||
7. Make a branch, make changes to the docs, and rebuild them as indicated in step 5. To speed up the build process, you can omit `clean` from the above command to rebuild only those pages that depend on the files you have changed. | ||
|
||
8. Once you are satisfied with your changes and the documentation builds successfully without errors or warnings, then git commit and push them to your "origin" repository on GitHub. | ||
|
||
git commit -m "commit message" | ||
git push -u origin --all # first time only, subsequent can be just 'git push'. | ||
|
||
9. Create a [pull request](https://help.github.com/articles/using-pull-requests/). | ||
|
||
10. Repeat the process starting from Step 6. |