From e1ddd184c7c1ebb4b7a5e333325da44e8b21c99d Mon Sep 17 00:00:00 2001 From: Richard Barrell Date: Mon, 7 Nov 2011 12:40:45 -0800 Subject: Current Pyramid uses 'pcreate' rather than 'paster create'. Update HACKING.txt to reflect this. --- HACKING.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 0194e9bab..98ab21e10 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -42,10 +42,10 @@ checkout. $ ../env/bin/python setup.py develop - At that point, you should be able to create new Pyramid projects by using - ``paster create``:: + ``pcreate``:: $ cd ../env - $ bin/paster create -t pyramid_starter starter + $ bin/pcreate -s starter starter - And install those projects (also using ``setup.py develop``) into the virtualenv:: -- cgit v1.2.3 From 29ce3d80418835a091ace00e2ec3a632f71f1577 Mon Sep 17 00:00:00 2001 From: Chris Shenton Date: Mon, 7 Nov 2011 16:09:42 -0800 Subject: CHANGES.txt says Pyramid no longer runs on 2.5 and earlier So don't require here in HACKING --- HACKING.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 98ab21e10..99a44fa01 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -61,8 +61,8 @@ In order to add a feature to Pyramid: - The feature must be documented in both the API and narrative documentation (in ``docs/``). -- The feature must work fully on the following CPython versions: 2.4, - 2.5, 2.6, and 2.7 on both UNIX and Windows. +- The feature must work fully on the following CPython versions: 2.6, + and 2.7 on both UNIX and Windows. - The feature must not cause installation or runtime failure on Jython or App Engine. If it doesn't cause installation or runtime failure, -- cgit v1.2.3 From a3ff61a5a554973e4c84c2120f0c6c019e192d9e Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 8 Nov 2011 15:55:53 -0800 Subject: fix hacking for trunk stuff --- HACKING.txt | 36 +++++++++++++++++++++++++++--------- 1 file changed, 27 insertions(+), 9 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 99a44fa01..d122a7a25 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -29,11 +29,6 @@ checkout. $ env/bin/easy_install setuptools-git -- Install ``nose`` and ``coverage`` into the virtualenv (for running nose - tests with coverage via ``setup.py nosetests --with-coverage``):: - - $ env/bin/easy_install nose coverage - - Install Pyramid from the checkout into the virtualenv using ``setup.py develop`` (running ``setup.py develop`` *must* be done while the current working directory is the ``pyramid`` checkout directory):: @@ -62,7 +57,9 @@ In order to add a feature to Pyramid: documentation (in ``docs/``). - The feature must work fully on the following CPython versions: 2.6, - and 2.7 on both UNIX and Windows. + 2.7, and 3.2 on both UNIX and Windows. + +- The feature must work on the latest version of PyPy. - The feature must not cause installation or runtime failure on Jython or App Engine. If it doesn't cause installation or runtime failure, @@ -88,12 +85,33 @@ Coding Style 2 newlines between classes. But 80-column lines, in particular, are mandatory. +Running Tests +-------------- + +- To run tests for Pyramid on a single Python version, run ``python setup.py + test`` against the using the Python interpreter from virtualenv into which + you've ``setup.py develop``-ed Pyramid. + +- To run the full set of Pyramid tests on all platforms, install ``tox`` + (http://codespeak.net/~hpk/tox/) into a system Python. The ``tox`` console + script will be installed into the scripts location for that Python. While + ``cd``'ed to the Pyramid checkout root directory (it contains ``tox.ini``), + invoke the ``tox`` console script. This will read the ``tox.ini`` file and + execute the tests on multiple Python versions and platforms; while it runs, + it creates a virtualenv for each version/platform combination. For + example:: + + $ /usr/bin/easy_install tox + $ cd ~/hack-on-pyramid/pyramid + $ /usr/bin/tox + Test Coverage ------------- -- The codebase *must* have 100% test statement coverage after each - commit. You can test coverage via ``python setup.py nosetests - --with-coverage`` (requires the ``nose`` and ``coverage`` packages). +- The codebase *must* have 100% test statement coverage after each commit. + You can test coverage via ``tox -e coverage``, or alternately by installing + ``nose`` and ``coverage`` into your virtualenv, and running ``setup.py + nosetests --with-coverage``. Documentation Coverage ---------------------- -- cgit v1.2.3 From 319806b49a8d2e8c8bbf61a1886eb206790d18e4 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 18 Nov 2011 07:51:48 -0500 Subject: add instructions about how to build docs (closes #348) --- HACKING.txt | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index d122a7a25..daa4f614b 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -121,6 +121,16 @@ Documentation Coverage that API or behavior must change to reflect the bug fix, ideally in the same commit that fixes the bug or adds the feature. +- To build and review docs: + + 1. Install ``tests_require`` dependencies from Pyramid's setup.py into your + virtualenv. + + 2. From the ``docs`` directory of the Pyramid checkout run ``make html + SPHINXBUILD=/path/to/your/virtualenv/bin/sphinx-build``. + + 3. Open the _build/html/index.html file to see the resulting rendering. + Change Log ---------- -- cgit v1.2.3 From 17863d878b4cc47342eb1e7606df99178700beb3 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 18 Nov 2011 09:47:06 -0500 Subject: paster template -> scaffold --- HACKING.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index daa4f614b..24d1b48a1 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -73,10 +73,10 @@ In order to add a feature to Pyramid: "unnecessary" is of course subjective, but new dependencies should be discussed). -The above requirements are relaxed for paster template dependencies. -If a paster template has an install-time dependency on something that -doesn't work on a particular platform, that caveat should be spelled -out clearly in *its* documentation (within its ``docs/`` directory). +The above requirements are relaxed for scaffolding dependencies. If a +scaffold has an install-time dependency on something that doesn't work on a +particular platform, that caveat should be spelled out clearly in *its* +documentation (within its ``docs/`` directory). Coding Style ------------ -- cgit v1.2.3 From 40b3a8a15e972a7d1dc0b0c7909d3e2a24f91afe Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 18 Nov 2011 09:47:40 -0500 Subject: remove jython --- HACKING.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 24d1b48a1..593e89ac1 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -61,10 +61,10 @@ In order to add a feature to Pyramid: - The feature must work on the latest version of PyPy. -- The feature must not cause installation or runtime failure on Jython - or App Engine. If it doesn't cause installation or runtime failure, - but doesn't actually *work* on these platforms, that caveat should be - spelled out in the documentation. +- The feature must not cause installation or runtime failure on App Engine. + If it doesn't cause installation or runtime failure, but doesn't actually + *work* on these platforms, that caveat should be spelled out in the + documentation. - The feature must not depend on any particular persistence layer (filesystem, SQL, etc). -- cgit v1.2.3 From 8c4210f94132e2ba844732bd1dada82696fc20db Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 11 Jun 2012 11:03:56 -0400 Subject: how to build HTML docs --- HACKING.txt | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 593e89ac1..ec0bcb000 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -48,6 +48,23 @@ checkout. $ cd starter $ ../bin/python setup.py develop +Building the HTML Docs +----------------------- + +- Check out Pyramid from Github. + +- Create a virtualenv or reuse an existing one that you're using to develop + Pyramid. + +- Run ``$yourvenv/bin/python setup.py dev docs``. + +- cd to ``docs`` within the Pyramid checkout and execute ``make clean html + SPHINXBUILD=$yourvenv/bin/sphinx-build``. The ``SPHINXBUILD=...`` hair is + there in order to tell it to use the virtualenv Python, which will have + both Sphinx and Pyramid (for API documentation generation) installed. + +- The rendered HTML docs will end up in ``docs/_build/html``. + Adding Features --------------- -- cgit v1.2.3 From c7fcdf1665cfdc1173559baa0a56d9a06fcba448 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 11 Jun 2012 11:16:07 -0400 Subject: consolidate --- HACKING.txt | 46 +++++++++++++++++----------------------------- 1 file changed, 17 insertions(+), 29 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index ec0bcb000..dd735bf22 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -48,23 +48,6 @@ checkout. $ cd starter $ ../bin/python setup.py develop -Building the HTML Docs ------------------------ - -- Check out Pyramid from Github. - -- Create a virtualenv or reuse an existing one that you're using to develop - Pyramid. - -- Run ``$yourvenv/bin/python setup.py dev docs``. - -- cd to ``docs`` within the Pyramid checkout and execute ``make clean html - SPHINXBUILD=$yourvenv/bin/sphinx-build``. The ``SPHINXBUILD=...`` hair is - there in order to tell it to use the virtualenv Python, which will have - both Sphinx and Pyramid (for API documentation generation) installed. - -- The rendered HTML docs will end up in ``docs/_build/html``. - Adding Features --------------- @@ -130,23 +113,28 @@ Test Coverage ``nose`` and ``coverage`` into your virtualenv, and running ``setup.py nosetests --with-coverage``. -Documentation Coverage ----------------------- +Documentation Coverage and Building HTML Documentation +------------------------------------------------------ -- If you fix a bug, and the bug requires an API or behavior - modification, all documentation in this package which references - that API or behavior must change to reflect the bug fix, ideally in - the same commit that fixes the bug or adds the feature. +If you fix a bug, and the bug requires an API or behavior modification, all +documentation in this package which references that API or behavior must +change to reflect the bug fix, ideally in the same commit that fixes the bug +or adds the feature. -- To build and review docs: +To build and review docs (where ``$yourvenv`` refers to the virtualenv you're +using to develop Pyramid): - 1. Install ``tests_require`` dependencies from Pyramid's setup.py into your - virtualenv. +1. Run ``$yourvenv/bin/python setup.py dev docs``. This will cause Sphinx + and all development requirements to be installed in your virtualenv. - 2. From the ``docs`` directory of the Pyramid checkout run ``make html - SPHINXBUILD=/path/to/your/virtualenv/bin/sphinx-build``. +2. cd to the ``docs`` directory within your Pyramid checkout and execute + ``make clean html SPHINXBUILD=$yourvenv/bin/sphinx-build``. The + ``SPHINXBUILD=...`` hair is there in order to tell it to use the + virtualenv Python, which will have both Sphinx and Pyramid (for API + documentation generation) installed. - 3. Open the _build/html/index.html file to see the resulting rendering. +3. Open the ``docs/_build/html/index.html`` file to see the resulting HTML + rendering. Change Log ---------- -- cgit v1.2.3 From 6ef753257617acf8aaf3daaca22de3783970cffe Mon Sep 17 00:00:00 2001 From: Jeff Cook Date: Wed, 4 Jul 2012 18:52:54 -0600 Subject: Include instructions for recursive submodule checkout of Sphinx themes. --- HACKING.txt | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index dd735bf22..38c263ed7 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -127,13 +127,19 @@ using to develop Pyramid): 1. Run ``$yourvenv/bin/python setup.py dev docs``. This will cause Sphinx and all development requirements to be installed in your virtualenv. -2. cd to the ``docs`` directory within your Pyramid checkout and execute +2. Update all git submodules from the top-level of your Pyramid checkout, like + so: + git submodule update --init --recursive + This will checkout theme subrepositories and prevent error conditions when + HTML docs are generated. + +3. cd to the ``docs`` directory within your Pyramid checkout and execute ``make clean html SPHINXBUILD=$yourvenv/bin/sphinx-build``. The ``SPHINXBUILD=...`` hair is there in order to tell it to use the virtualenv Python, which will have both Sphinx and Pyramid (for API documentation generation) installed. -3. Open the ``docs/_build/html/index.html`` file to see the resulting HTML +4. Open the ``docs/_build/html/index.html`` file to see the resulting HTML rendering. Change Log -- cgit v1.2.3 From cdcea948c3f6f3abbd1772500029066e80825082 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 15 Aug 2012 12:57:29 -0400 Subject: note whitespace rules, explain setup.py dev --- HACKING.txt | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 38c263ed7..87d1422dc 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -30,11 +30,13 @@ checkout. $ env/bin/easy_install setuptools-git - Install Pyramid from the checkout into the virtualenv using ``setup.py - develop`` (running ``setup.py develop`` *must* be done while the current - working directory is the ``pyramid`` checkout directory):: + dev``. ``setup.py dev`` is an alias for "setup.py develop" which also + installs testing requirements such as nose and coverage. Running + ``setup.py dev`` *must* be done while the current working directory is the + ``pyramid`` checkout directory:: $ cd pyramid - $ ../env/bin/python setup.py develop + $ ../env/bin/python setup.py dev - At that point, you should be able to create new Pyramid projects by using ``pcreate``:: @@ -85,6 +87,9 @@ Coding Style 2 newlines between classes. But 80-column lines, in particular, are mandatory. +- Please do not remove trailing whitespace. Configure your editor to reduce + diff noise. + Running Tests -------------- @@ -110,8 +115,8 @@ Test Coverage - The codebase *must* have 100% test statement coverage after each commit. You can test coverage via ``tox -e coverage``, or alternately by installing - ``nose`` and ``coverage`` into your virtualenv, and running ``setup.py - nosetests --with-coverage``. + ``nose`` and ``coverage`` into your virtualenv (easiest via ``setup.py + dev``) , and running ``setup.py nosetests --with-coverage``. Documentation Coverage and Building HTML Documentation ------------------------------------------------------ -- cgit v1.2.3 From b98e70e340f84652b44c888472724a23bae5f007 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 12 Jan 2013 01:55:27 +0200 Subject: grammar --- HACKING.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 87d1422dc..64c8f461a 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -94,7 +94,7 @@ Running Tests -------------- - To run tests for Pyramid on a single Python version, run ``python setup.py - test`` against the using the Python interpreter from virtualenv into which + test`` against the Python interpreter from virtualenv into which you've ``setup.py develop``-ed Pyramid. - To run the full set of Pyramid tests on all platforms, install ``tox`` -- cgit v1.2.3 From 8a3872de6761eed9d372f1363ebb01ac313d4543 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 15 Jan 2013 08:26:55 +0200 Subject: fix #788 --- HACKING.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 64c8f461a..32381cc6c 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -88,7 +88,7 @@ Coding Style mandatory. - Please do not remove trailing whitespace. Configure your editor to reduce - diff noise. + diff noise. See https://github.com/Pylons/pyramid/issues/788 for more. Running Tests -------------- -- cgit v1.2.3 From f73f0e332658fac2583f51247dcd49bd36d63ce4 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 13 Mar 2013 23:05:17 +0200 Subject: consistency: use $VENV whenever virtualenv binaries are used --- HACKING.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 32381cc6c..26e85ee80 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -27,7 +27,7 @@ checkout. - Install ``setuptools-git`` into the virtualenv (for good measure, as we're using git to do version control):: - $ env/bin/easy_install setuptools-git + $ $VENV/bin/easy_install setuptools-git - Install Pyramid from the checkout into the virtualenv using ``setup.py dev``. ``setup.py dev`` is an alias for "setup.py develop" which also @@ -36,19 +36,19 @@ checkout. ``pyramid`` checkout directory:: $ cd pyramid - $ ../env/bin/python setup.py dev + $ $VENV/bin/python setup.py dev - At that point, you should be able to create new Pyramid projects by using ``pcreate``:: $ cd ../env - $ bin/pcreate -s starter starter + $ $VENV/bin/pcreate -s starter starter - And install those projects (also using ``setup.py develop``) into the virtualenv:: $ cd starter - $ ../bin/python setup.py develop + $ $VENV/bin/python setup.py develop Adding Features --------------- @@ -129,7 +129,7 @@ or adds the feature. To build and review docs (where ``$yourvenv`` refers to the virtualenv you're using to develop Pyramid): -1. Run ``$yourvenv/bin/python setup.py dev docs``. This will cause Sphinx +1. Run ``$VENV/bin/python setup.py dev docs``. This will cause Sphinx and all development requirements to be installed in your virtualenv. 2. Update all git submodules from the top-level of your Pyramid checkout, like @@ -139,7 +139,7 @@ using to develop Pyramid): HTML docs are generated. 3. cd to the ``docs`` directory within your Pyramid checkout and execute - ``make clean html SPHINXBUILD=$yourvenv/bin/sphinx-build``. The + ``make clean html SPHINXBUILD=$VENV/bin/sphinx-build``. The ``SPHINXBUILD=...`` hair is there in order to tell it to use the virtualenv Python, which will have both Sphinx and Pyramid (for API documentation generation) installed. -- cgit v1.2.3 From 2d045be54b8671a062b886c613b3f4e3e88ff7c9 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 12 Jul 2013 21:05:46 -0600 Subject: Make abstraction consistent. --- HACKING.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 26e85ee80..5b5dcc458 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -126,7 +126,7 @@ documentation in this package which references that API or behavior must change to reflect the bug fix, ideally in the same commit that fixes the bug or adds the feature. -To build and review docs (where ``$yourvenv`` refers to the virtualenv you're +To build and review docs (where ``$VENV`` refers to the virtualenv you're using to develop Pyramid): 1. Run ``$VENV/bin/python setup.py dev docs``. This will cause Sphinx -- cgit v1.2.3 From 00a08a307574b231a5a8c1142bc675732a03632b Mon Sep 17 00:00:00 2001 From: Tom Lazar Date: Fri, 16 Aug 2013 14:26:57 +0200 Subject: add custom tox config that creates a development environment --- HACKING.txt | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 5b5dcc458..563903f2f 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -16,13 +16,31 @@ checkout. - Check out a read-only copy of the Pyramid source:: - $ git clone git://github.com/Pylons/pyramid.git + $ git clone git://github.com/Pylons/pyramid.git . (alternately, create a writeable fork on GitHub and check that out). +Since pyramid is a framework and not an application, it can be +convenient to work against a sample application, preferably in its +own virtualenv. A quick way to achieve this is to (ab-)use ``tox`` +with a custom configuration file that's part of the checkout:: + + tox -c hacking-tox.ini + +This will create a python-2.7 based virtualenv named ``env27`` (pyramid's +``.gitconfig` ignores all top-level folders that start with ``env`` specifically +for this use case) and inside that a simple pyramid application named +``hacking`` that you can then fire up like so:: + + cd env27/hacking + ../bin/pserve development.ini + +Alternatively, if you don't want to install ``tox`` at this point, +you an achieve the same manually by following these steps: + - Create a virtualenv in which to install Pyramid:: - $ virtualenv2.6 --no-site-packages env + $ virtualenv --no-site-packages env - Install ``setuptools-git`` into the virtualenv (for good measure, as we're using git to do version control):: -- cgit v1.2.3 From 7a2df29602b207954a4d00fae4556f57ed3675e1 Mon Sep 17 00:00:00 2001 From: Andreas Zeidler Date: Fri, 16 Aug 2013 16:42:08 +0200 Subject: add info how to run the tests using pytest (http://pytest.org/) --- HACKING.txt | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 563903f2f..87538d0ad 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -128,6 +128,13 @@ Running Tests $ cd ~/hack-on-pyramid/pyramid $ /usr/bin/tox +- The tests can also be run usign ``pytest`` (http://pytest.org/). This is + intended as a convenience for people who are more used or fond of ``pytest``. + Run the tests like so:: + + $ pip install pytest + $ py.test --strict pyramid/ + Test Coverage ------------- -- cgit v1.2.3 From 852e015f9b3864b0c07569a9753c4107b8d1238a Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Fri, 16 Aug 2013 09:48:19 -0500 Subject: recommend easy_install until we don't --- HACKING.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 87538d0ad..5d33aa0ab 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -40,7 +40,7 @@ you an achieve the same manually by following these steps: - Create a virtualenv in which to install Pyramid:: - $ virtualenv --no-site-packages env + $ virtualenv env - Install ``setuptools-git`` into the virtualenv (for good measure, as we're using git to do version control):: @@ -132,7 +132,7 @@ Running Tests intended as a convenience for people who are more used or fond of ``pytest``. Run the tests like so:: - $ pip install pytest + $ $VENV/bin/easy_install pytest $ py.test --strict pyramid/ Test Coverage -- cgit v1.2.3 From 68d2a8cf14b940ffac796be663baeb0782640310 Mon Sep 17 00:00:00 2001 From: Tom Lazar Date: Sat, 17 Aug 2013 16:08:43 +0200 Subject: provide the tox url when mentioning it first. --- HACKING.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 563903f2f..2e444e781 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -23,7 +23,8 @@ checkout. Since pyramid is a framework and not an application, it can be convenient to work against a sample application, preferably in its own virtualenv. A quick way to achieve this is to (ab-)use ``tox`` -with a custom configuration file that's part of the checkout:: +(http://codespeak.net/~hpk/tox/) with a custom configuration file that's part of +the checkout:: tox -c hacking-tox.ini -- cgit v1.2.3 From 98b383ef54d16c977561101dde1addd34ba34240 Mon Sep 17 00:00:00 2001 From: Tom Lazar Date: Sat, 17 Aug 2013 16:09:58 +0200 Subject: adjust the checkout path to the new value set above in a previous commit --- HACKING.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 2e444e781..d664d6bfc 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -126,7 +126,7 @@ Running Tests example:: $ /usr/bin/easy_install tox - $ cd ~/hack-on-pyramid/pyramid + $ cd ~/hack-on-pyramid/ $ /usr/bin/tox Test Coverage -- cgit v1.2.3 From 50f23dd4fb2ea8690893ac2cf20a0f0483b32a0d Mon Sep 17 00:00:00 2001 From: Tom Lazar Date: Sat, 17 Aug 2013 16:10:45 +0200 Subject: include and mention the `nose-selecttests `_ plugin --- HACKING.txt | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index d664d6bfc..0d28905b6 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -112,9 +112,13 @@ Coding Style Running Tests -------------- -- To run tests for Pyramid on a single Python version, run ``python setup.py - test`` against the Python interpreter from virtualenv into which - you've ``setup.py develop``-ed Pyramid. +- To run all tests for Pyramid on a single Python version, run ``nosetests`` from + your development virtualenv (See *Using a Development Checkout* above). + +- To run individual tests (i.e. during development) you can use a regular + expression with the ``-t`` parameter courtesy of the `nose-selecttests + `_ plugin that's been installed (along with nose itself) via ``python setup.py dev``. The easiest usage is to + simply provide the verbatim name of the test you're working on. - To run the full set of Pyramid tests on all platforms, install ``tox`` (http://codespeak.net/~hpk/tox/) into a system Python. The ``tox`` console -- cgit v1.2.3 From 13b1871878932091e56b01bb27eef7033521a83f Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 5 Sep 2013 23:23:27 -0400 Subject: update HACKING --- HACKING.txt | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index abfed6dab..684a42ee6 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -78,7 +78,7 @@ In order to add a feature to Pyramid: documentation (in ``docs/``). - The feature must work fully on the following CPython versions: 2.6, - 2.7, and 3.2 on both UNIX and Windows. + 2.7, 3.2, and 3.3 on both UNIX and Windows. - The feature must work on the latest version of PyPy. @@ -104,7 +104,9 @@ Coding Style - PEP8 compliance. Whitespace rules are relaxed: not necessary to put 2 newlines between classes. But 80-column lines, in particular, are - mandatory. + mandatory. See + http://docs.pylonsproject.org/en/latest/community/codestyle.html for more + information. - Please do not remove trailing whitespace. Configure your editor to reduce diff noise. See https://github.com/Pylons/pyramid/issues/788 for more. @@ -112,13 +114,15 @@ Coding Style Running Tests -------------- -- To run all tests for Pyramid on a single Python version, run ``nosetests`` from - your development virtualenv (See *Using a Development Checkout* above). +- To run all tests for Pyramid on a single Python version, run ``nosetests`` + from your development virtualenv (See *Using a Development Checkout* above). - To run individual tests (i.e. during development) you can use a regular expression with the ``-t`` parameter courtesy of the `nose-selecttests - `_ plugin that's been installed (along with nose itself) via ``python setup.py dev``. The easiest usage is to - simply provide the verbatim name of the test you're working on. + `_ plugin that's been + installed (along with nose itself) via ``python setup.py dev``. The + easiest usage is to simply provide the verbatim name of the test you're + working on. - To run the full set of Pyramid tests on all platforms, install ``tox`` (http://codespeak.net/~hpk/tox/) into a system Python. The ``tox`` console -- cgit v1.2.3 From 93137f090f24b1ffa4812b282adf95708576c1a1 Mon Sep 17 00:00:00 2001 From: Adam Gomaa Date: Thu, 12 Sep 2013 14:16:39 -0700 Subject: fix broken link to tox --- HACKING.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 684a42ee6..4ebb59160 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -21,10 +21,10 @@ checkout. (alternately, create a writeable fork on GitHub and check that out). Since pyramid is a framework and not an application, it can be -convenient to work against a sample application, preferably in its -own virtualenv. A quick way to achieve this is to (ab-)use ``tox`` -(http://codespeak.net/~hpk/tox/) with a custom configuration file that's part of -the checkout:: +convenient to work against a sample application, preferably in its own +virtualenv. A quick way to achieve this is to (ab-)use ``tox`` +(http://tox.readthedocs.org/en/latest/) with a custom configuration +file that's part of the checkout:: tox -c hacking-tox.ini -- cgit v1.2.3 From 9951556030aeed07978472f59b7843273bcb84a8 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 4 Oct 2013 21:53:46 -0400 Subject: normalize tox-vs-byhand, add note about --no-site-packages, tell folks to use 'setup.py docs' and not 'setup.py dev docs' based on report from karlping --- HACKING.txt | 121 ++++++++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 80 insertions(+), 41 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 4ebb59160..be67000ce 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -6,47 +6,43 @@ Here are some guidelines about hacking on Pyramid. Using a Development Checkout ---------------------------- -Below is a quick start on creating a development environment using a Pyramid -checkout. +You'll have to create a development environment to hack on Pyramid, using a +Pyramid checkout. You can either do this by hand or, if you have ``tox`` +installed (it's on PyPI), you can (ab)use tox to get a working development +environment. Each installation method is described below. -- Create a new directory somewhere and ``cd`` to it:: - - $ mkdir ~/hack-on-pyramid - $ cd ~/hack-on-pyramid - -- Check out a read-only copy of the Pyramid source:: +By Hand ++++++++ - $ git clone git://github.com/Pylons/pyramid.git . +- Check out Pyramid from source:: - (alternately, create a writeable fork on GitHub and check that out). - -Since pyramid is a framework and not an application, it can be -convenient to work against a sample application, preferably in its own -virtualenv. A quick way to achieve this is to (ab-)use ``tox`` -(http://tox.readthedocs.org/en/latest/) with a custom configuration -file that's part of the checkout:: - - tox -c hacking-tox.ini + $ cd ~ + $ git clone git://github.com/Pylons/pyramid.git hack-on-pyramid + $ cd hack-on-pyramid -This will create a python-2.7 based virtualenv named ``env27`` (pyramid's -``.gitconfig` ignores all top-level folders that start with ``env`` specifically -for this use case) and inside that a simple pyramid application named -``hacking`` that you can then fire up like so:: +- Create a virtualenv in which to install Pyramid:: - cd env27/hacking - ../bin/pserve development.ini + $ cd ~/hack-on-pyramid + $ virtualenv -ppython2.7 env -Alternatively, if you don't want to install ``tox`` at this point, -you an achieve the same manually by following these steps: + Note that very old versions of virtualenv (virtualenv versions below, say, + 1.10 or thereabouts) require you to pass a ``--no-site-packages`` flag to + get a completely isolated environment. If you're on an old system, use + ``virtualenv --no-site-packages`` instead of ``virtualenv`` above. -- Create a virtualenv in which to install Pyramid:: + You can choose which Python version you want to use by passing a ``-p`` + flag to ``virtualenv``. For example, ``virtualenv -ppython2.7`` + chooses the Python 2.7 interpreter to be installed. - $ virtualenv env + From here on in within these instructions, the ``~/hack-on-pyramid/env`` + virtual environment you created above will be referred to as ``$VENV``. + To use the instructions in the steps that follow literally, use the + ``export VENV=~/hack-on-pyramid/env`` command. - Install ``setuptools-git`` into the virtualenv (for good measure, as we're using git to do version control):: - $ $VENV/bin/easy_install setuptools-git + $ $VENV/bin/easy_install setuptools-git - Install Pyramid from the checkout into the virtualenv using ``setup.py dev``. ``setup.py dev`` is an alias for "setup.py develop" which also @@ -54,21 +50,54 @@ you an achieve the same manually by following these steps: ``setup.py dev`` *must* be done while the current working directory is the ``pyramid`` checkout directory:: - $ cd pyramid - $ $VENV/bin/python setup.py dev + $ cd ~/hack-on-pyramid + $ $VENV/bin/python setup.py dev - At that point, you should be able to create new Pyramid projects by using ``pcreate``:: - $ cd ../env - $ $VENV/bin/pcreate -s starter starter + $ cd $VENV + $ bin/pcreate -s starter starter - And install those projects (also using ``setup.py develop``) into the virtualenv:: - $ cd starter + $ cd $VENV/starter $ $VENV/bin/python setup.py develop +Using Tox ++++++++++ + +Alternatively, if you already have ``tox`` installed, there is an easier +way to get going. + +- Create a new directory somewhere and ``cd`` to it:: + + $ mkdir ~/hack-on-pyramid + $ cd ~/hack-on-pyramid + +- Check out a read-only copy of the Pyramid source:: + + $ git clone git://github.com/Pylons/pyramid.git . + + (alternately, create a writeable fork on GitHub and check that out). + +Since pyramid is a framework and not an application, it can be +convenient to work against a sample application, preferably in its own +virtualenv. A quick way to achieve this is to (ab-)use ``tox`` +(http://tox.readthedocs.org/en/latest/) with a custom configuration +file that's part of the checkout:: + + tox -c hacking-tox.ini + +This will create a python-2.7 based virtualenv named ``env27`` (pyramid's +``.gitconfig` ignores all top-level folders that start with ``env`` specifically +for this use case) and inside that a simple pyramid application named +``hacking`` that you can then fire up like so:: + + cd env27/hacking + ../bin/pserve development.ini + Adding Features --------------- @@ -133,7 +162,7 @@ Running Tests it creates a virtualenv for each version/platform combination. For example:: - $ /usr/bin/easy_install tox + $ sudo /usr/bin/easy_install tox $ cd ~/hack-on-pyramid/ $ /usr/bin/tox @@ -163,18 +192,28 @@ or adds the feature. To build and review docs (where ``$VENV`` refers to the virtualenv you're using to develop Pyramid): -1. Run ``$VENV/bin/python setup.py dev docs``. This will cause Sphinx - and all development requirements to be installed in your virtualenv. +1. After follwing the steps above in "Using a Development Checkout", cause + Sphinx and all development requirements to be installed in your + virtualenv:: + + $ cd ~/hack-on-pyramid + $ $VENV/bin/python setup.py docs 2. Update all git submodules from the top-level of your Pyramid checkout, like - so: - git submodule update --init --recursive + so:: + + $ git submodule update --init --recursive + This will checkout theme subrepositories and prevent error conditions when HTML docs are generated. 3. cd to the ``docs`` directory within your Pyramid checkout and execute - ``make clean html SPHINXBUILD=$VENV/bin/sphinx-build``. The - ``SPHINXBUILD=...`` hair is there in order to tell it to use the + the ``make`` command with some flags:: + + $ cd ~/hack-on-pyramid/pyramid/docs + $ make clean html SPHINXBUILD=$VENV/bin/sphinx-build + + The ``SPHINXBUILD=...`` hair is there in order to tell it to use the virtualenv Python, which will have both Sphinx and Pyramid (for API documentation generation) installed. -- cgit v1.2.3 From 41ce5c5ce42288d7a4ad26e405c4681530379e35 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Fri, 11 Oct 2013 22:54:23 +0200 Subject: docs: rm redundancy --- HACKING.txt | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index be67000ce..eab3889ca 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -27,8 +27,7 @@ By Hand Note that very old versions of virtualenv (virtualenv versions below, say, 1.10 or thereabouts) require you to pass a ``--no-site-packages`` flag to - get a completely isolated environment. If you're on an old system, use - ``virtualenv --no-site-packages`` instead of ``virtualenv`` above. + get a completely isolated environment. You can choose which Python version you want to use by passing a ``-p`` flag to ``virtualenv``. For example, ``virtualenv -ppython2.7`` -- cgit v1.2.3 From d53fd254ccb82b17b590fb236ce9671c8a80c567 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Fri, 11 Oct 2013 22:55:07 +0200 Subject: docs: capitalise --- HACKING.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index eab3889ca..683ac61f5 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -81,7 +81,7 @@ way to get going. (alternately, create a writeable fork on GitHub and check that out). -Since pyramid is a framework and not an application, it can be +Since Pyramid is a framework and not an application, it can be convenient to work against a sample application, preferably in its own virtualenv. A quick way to achieve this is to (ab-)use ``tox`` (http://tox.readthedocs.org/en/latest/) with a custom configuration @@ -89,7 +89,7 @@ file that's part of the checkout:: tox -c hacking-tox.ini -This will create a python-2.7 based virtualenv named ``env27`` (pyramid's +This will create a python-2.7 based virtualenv named ``env27`` (Pyramid's ``.gitconfig` ignores all top-level folders that start with ``env`` specifically for this use case) and inside that a simple pyramid application named ``hacking`` that you can then fire up like so:: -- cgit v1.2.3 From e7ad85361379bc0d8276a2583ae20ac84b3989c8 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Fri, 11 Oct 2013 22:55:17 +0200 Subject: docs: typos --- HACKING.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 683ac61f5..b32a8a957 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -165,7 +165,7 @@ Running Tests $ cd ~/hack-on-pyramid/ $ /usr/bin/tox -- The tests can also be run usign ``pytest`` (http://pytest.org/). This is +- The tests can also be run using ``pytest`` (http://pytest.org/). This is intended as a convenience for people who are more used or fond of ``pytest``. Run the tests like so:: @@ -191,7 +191,7 @@ or adds the feature. To build and review docs (where ``$VENV`` refers to the virtualenv you're using to develop Pyramid): -1. After follwing the steps above in "Using a Development Checkout", cause +1. After following the steps above in "Using a Development Checkout", cause Sphinx and all development requirements to be installed in your virtualenv:: -- cgit v1.2.3 From 7c81e0f5296455248b787c9dd755793dec99ba7c Mon Sep 17 00:00:00 2001 From: Ole Morten Halvorsen Date: Wed, 20 Nov 2013 20:53:54 +1100 Subject: Fixed typo - removed 'hair'. --- HACKING.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index b32a8a957..3c83261c7 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -212,9 +212,9 @@ using to develop Pyramid): $ cd ~/hack-on-pyramid/pyramid/docs $ make clean html SPHINXBUILD=$VENV/bin/sphinx-build - The ``SPHINXBUILD=...`` hair is there in order to tell it to use the - virtualenv Python, which will have both Sphinx and Pyramid (for API - documentation generation) installed. + The ``SPHINXBUILD=...`` is there to tell it to use the virtualenv Python, + which will have both Sphinx and Pyramid (for API documentation + generation) installed. 4. Open the ``docs/_build/html/index.html`` file to see the resulting HTML rendering. -- cgit v1.2.3 From a767d8b0a54b4e93515c3faa4348bc4a34eed0cb Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 20 Nov 2013 02:43:52 -0800 Subject: improve grammar and remove slang --- HACKING.txt | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 3c83261c7..12f2d68e2 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -6,9 +6,9 @@ Here are some guidelines about hacking on Pyramid. Using a Development Checkout ---------------------------- -You'll have to create a development environment to hack on Pyramid, using a -Pyramid checkout. You can either do this by hand or, if you have ``tox`` -installed (it's on PyPI), you can (ab)use tox to get a working development +You'll have to create a development environment to hack on Pyramid, using a +Pyramid checkout. You can either do this by hand or, if you have ``tox`` +installed (it's on PyPI), you can (ab)use tox to get a working development environment. Each installation method is described below. By Hand @@ -25,15 +25,15 @@ By Hand $ cd ~/hack-on-pyramid $ virtualenv -ppython2.7 env - Note that very old versions of virtualenv (virtualenv versions below, say, + Note that very old versions of virtualenv (virtualenv versions below, say, 1.10 or thereabouts) require you to pass a ``--no-site-packages`` flag to get a completely isolated environment. - You can choose which Python version you want to use by passing a ``-p`` + You can choose which Python version you want to use by passing a ``-p`` flag to ``virtualenv``. For example, ``virtualenv -ppython2.7`` chooses the Python 2.7 interpreter to be installed. - From here on in within these instructions, the ``~/hack-on-pyramid/env`` + From here on in within these instructions, the ``~/hack-on-pyramid/env`` virtual environment you created above will be referred to as ``$VENV``. To use the instructions in the steps that follow literally, use the ``export VENV=~/hack-on-pyramid/env`` command. @@ -132,7 +132,7 @@ Coding Style - PEP8 compliance. Whitespace rules are relaxed: not necessary to put 2 newlines between classes. But 80-column lines, in particular, are - mandatory. See + mandatory. See http://docs.pylonsproject.org/en/latest/community/codestyle.html for more information. @@ -142,14 +142,14 @@ Coding Style Running Tests -------------- -- To run all tests for Pyramid on a single Python version, run ``nosetests`` +- To run all tests for Pyramid on a single Python version, run ``nosetests`` from your development virtualenv (See *Using a Development Checkout* above). - To run individual tests (i.e. during development) you can use a regular expression with the ``-t`` parameter courtesy of the `nose-selecttests - `_ plugin that's been - installed (along with nose itself) via ``python setup.py dev``. The - easiest usage is to simply provide the verbatim name of the test you're + `_ plugin that's been + installed (along with nose itself) via ``python setup.py dev``. The + easiest usage is to simply provide the verbatim name of the test you're working on. - To run the full set of Pyramid tests on all platforms, install ``tox`` @@ -191,8 +191,8 @@ or adds the feature. To build and review docs (where ``$VENV`` refers to the virtualenv you're using to develop Pyramid): -1. After following the steps above in "Using a Development Checkout", cause - Sphinx and all development requirements to be installed in your +1. After following the steps above in "Using a Development Checkout", cause + Sphinx and all development requirements to be installed in your virtualenv:: $ cd ~/hack-on-pyramid @@ -212,9 +212,9 @@ using to develop Pyramid): $ cd ~/hack-on-pyramid/pyramid/docs $ make clean html SPHINXBUILD=$VENV/bin/sphinx-build - The ``SPHINXBUILD=...`` is there to tell it to use the virtualenv Python, - which will have both Sphinx and Pyramid (for API documentation - generation) installed. + The ``SPHINXBUILD=...`` argument tells Sphinx to use the virtualenv Python, + which will have both Sphinx and Pyramid (for API documentation generation) + installed. 4. Open the ``docs/_build/html/index.html`` file to see the resulting HTML rendering. -- cgit v1.2.3 From 93b6cd09e08055061722bc619092a4f061e1634d Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 9 Feb 2014 22:46:57 -0600 Subject: - Add more git submodule instructions - Add steps to fork and clone Pyramid to GitHub repo, then clone user GitHub repo to local machine. --- HACKING.txt | 81 ++++++++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 53 insertions(+), 28 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 12f2d68e2..460d02047 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -1,26 +1,45 @@ Hacking on Pyramid ================== -Here are some guidelines about hacking on Pyramid. +Here are some guidelines for hacking on Pyramid. Using a Development Checkout ---------------------------- You'll have to create a development environment to hack on Pyramid, using a -Pyramid checkout. You can either do this by hand or, if you have ``tox`` -installed (it's on PyPI), you can (ab)use tox to get a working development +Pyramid checkout. You can either do this by hand, or if you have ``tox`` +installed (it's on PyPI), you can use tox to set up a working development environment. Each installation method is described below. By Hand +++++++ -- Check out Pyramid from source:: +- While logged into your GitHub account, navigate to the Pyramid repo on + GitHub. + + https://github.com/Pylons/pyramid + +- Fork and clone the Pyramid repository to your GitHub account by clicking + the "Fork" button. + +- Clone your fork of Pyramid from your GitHub account to your local computer, + substituting your account username and specifying the destination as + "hack-on-pyramid". $ cd ~ - $ git clone git://github.com/Pylons/pyramid.git hack-on-pyramid + $ git clone git@github.com:USERNAME/pyramid.git hack-on-pyramid $ cd hack-on-pyramid + # Configure remotes such that you can pull changes from the Pyramid + # repository into your local repository. + $ git remote add upstream git@github.com:Pylons/pyramid.git + # fetch and merge changes from upstream into master + $ git fetch upstream + $ git merge upstream/master + +Now your local repo is set up such that you will push changes to your GitHub +repo, from which you can submit a pull request. -- Create a virtualenv in which to install Pyramid:: +- Create a virtualenv in which to install Pyramid: $ cd ~/hack-on-pyramid $ virtualenv -ppython2.7 env @@ -39,7 +58,7 @@ By Hand ``export VENV=~/hack-on-pyramid/env`` command. - Install ``setuptools-git`` into the virtualenv (for good measure, as we're - using git to do version control):: + using git to do version control): $ $VENV/bin/easy_install setuptools-git @@ -47,19 +66,18 @@ By Hand dev``. ``setup.py dev`` is an alias for "setup.py develop" which also installs testing requirements such as nose and coverage. Running ``setup.py dev`` *must* be done while the current working directory is the - ``pyramid`` checkout directory:: + ``pyramid`` checkout directory: $ cd ~/hack-on-pyramid $ $VENV/bin/python setup.py dev -- At that point, you should be able to create new Pyramid projects by using - ``pcreate``:: +- Optionally create a new Pyramid project using ``pcreate``: $ cd $VENV $ bin/pcreate -s starter starter -- And install those projects (also using ``setup.py develop``) into the - virtualenv:: +- ...and install the new project (also using ``setup.py develop``) into the + virtualenv: $ cd $VENV/starter $ $VENV/bin/python setup.py develop @@ -70,12 +88,12 @@ Using Tox Alternatively, if you already have ``tox`` installed, there is an easier way to get going. -- Create a new directory somewhere and ``cd`` to it:: +- Create a new directory somewhere and ``cd`` to it: $ mkdir ~/hack-on-pyramid $ cd ~/hack-on-pyramid -- Check out a read-only copy of the Pyramid source:: +- Check out a read-only copy of the Pyramid source: $ git clone git://github.com/Pylons/pyramid.git . @@ -85,14 +103,14 @@ Since Pyramid is a framework and not an application, it can be convenient to work against a sample application, preferably in its own virtualenv. A quick way to achieve this is to (ab-)use ``tox`` (http://tox.readthedocs.org/en/latest/) with a custom configuration -file that's part of the checkout:: +file that's part of the checkout: tox -c hacking-tox.ini This will create a python-2.7 based virtualenv named ``env27`` (Pyramid's ``.gitconfig` ignores all top-level folders that start with ``env`` specifically for this use case) and inside that a simple pyramid application named -``hacking`` that you can then fire up like so:: +``hacking`` that you can then fire up like so: cd env27/hacking ../bin/pserve development.ini @@ -159,7 +177,7 @@ Running Tests invoke the ``tox`` console script. This will read the ``tox.ini`` file and execute the tests on multiple Python versions and platforms; while it runs, it creates a virtualenv for each version/platform combination. For - example:: + example: $ sudo /usr/bin/easy_install tox $ cd ~/hack-on-pyramid/ @@ -167,7 +185,7 @@ Running Tests - The tests can also be run using ``pytest`` (http://pytest.org/). This is intended as a convenience for people who are more used or fond of ``pytest``. - Run the tests like so:: + Run the tests like so: $ $VENV/bin/easy_install pytest $ py.test --strict pyramid/ @@ -184,30 +202,38 @@ Documentation Coverage and Building HTML Documentation ------------------------------------------------------ If you fix a bug, and the bug requires an API or behavior modification, all -documentation in this package which references that API or behavior must -change to reflect the bug fix, ideally in the same commit that fixes the bug +documentation in this package which references that API or behavior must be +changed to reflect the bug fix, ideally in the same commit that fixes the bug or adds the feature. To build and review docs (where ``$VENV`` refers to the virtualenv you're using to develop Pyramid): -1. After following the steps above in "Using a Development Checkout", cause - Sphinx and all development requirements to be installed in your - virtualenv:: +1. After following the steps above in "Using a Development Checkout", install + Sphinx and all development requirements in your virtualenv: $ cd ~/hack-on-pyramid $ $VENV/bin/python setup.py docs 2. Update all git submodules from the top-level of your Pyramid checkout, like - so:: + so: $ git submodule update --init --recursive This will checkout theme subrepositories and prevent error conditions when HTML docs are generated. -3. cd to the ``docs`` directory within your Pyramid checkout and execute - the ``make`` command with some flags:: +3. Next change into the submodule's directory and switch to a branch so that + the submodule repositories are no longer "headless". Then update the + repository to ensure that we have the latest updates. + See http://chrisjean.com/2009/04/20/git-submodules-adding-using-removing-and-updating/ + + $ cd docs/_themes + $ git checkout master + $ git pull + +4. Change into the ``docs`` directory within your Pyramid checkout and execute + the ``make`` command with some flags: $ cd ~/hack-on-pyramid/pyramid/docs $ make clean html SPHINXBUILD=$VENV/bin/sphinx-build @@ -216,7 +242,7 @@ using to develop Pyramid): which will have both Sphinx and Pyramid (for API documentation generation) installed. -4. Open the ``docs/_build/html/index.html`` file to see the resulting HTML +5. Open the ``docs/_build/html/index.html`` file to see the resulting HTML rendering. Change Log @@ -227,4 +253,3 @@ Change Log descriptive, not cryptic. Other developers should be able to know what your changelog entry means. - -- cgit v1.2.3 From 176914bfea1de3f04617ecde594c07600d8842c4 Mon Sep 17 00:00:00 2001 From: Leonardo Jimenez Date: Mon, 14 Apr 2014 17:38:12 -0400 Subject: Modified the way anonymous commiters configure the remote, the older version only worked for users with access to the repository as commiters. --- HACKING.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 460d02047..8e2c049c2 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -31,7 +31,7 @@ By Hand $ cd hack-on-pyramid # Configure remotes such that you can pull changes from the Pyramid # repository into your local repository. - $ git remote add upstream git@github.com:Pylons/pyramid.git + $ git remote add upstream https://github.com:Pylons/pyramid.git # fetch and merge changes from upstream into master $ git fetch upstream $ git merge upstream/master -- cgit v1.2.3 From 4e0d3f5ad9d556db1683a6fce5082543695c3f6f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 20 Apr 2014 03:46:06 -0700 Subject: - Correct 80-column lines specification to 79 to be compliant with PEP8 and consistent with doc to which this line refers. --- HACKING.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 8e2c049c2..1386be3af 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -149,7 +149,7 @@ Coding Style ------------ - PEP8 compliance. Whitespace rules are relaxed: not necessary to put - 2 newlines between classes. But 80-column lines, in particular, are + 2 newlines between classes. But 79-column lines, in particular, are mandatory. See http://docs.pylonsproject.org/en/latest/community/codestyle.html for more information. -- cgit v1.2.3 From 25d8b9790a613f5a0bbdf30b1c3f70b0d212e41a Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 17 Aug 2014 23:39:39 -0700 Subject: - add missing step for tox setup --- HACKING.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 1386be3af..e3afbf241 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -113,6 +113,7 @@ for this use case) and inside that a simple pyramid application named ``hacking`` that you can then fire up like so: cd env27/hacking + ../bin/python setup.py develop ../bin/pserve development.ini Adding Features -- cgit v1.2.3 From 39c7e4fec6265355b3eefb77a5dfbf9d6fc26ded Mon Sep 17 00:00:00 2001 From: Matt Russell Date: Wed, 19 Nov 2014 23:20:01 +0000 Subject: Correct url in git remote command. --- HACKING.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index e3afbf241..16c17699c 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -31,7 +31,7 @@ By Hand $ cd hack-on-pyramid # Configure remotes such that you can pull changes from the Pyramid # repository into your local repository. - $ git remote add upstream https://github.com:Pylons/pyramid.git + $ git remote add upstream https://github.com/Pylons/pyramid.git # fetch and merge changes from upstream into master $ git fetch upstream $ git merge upstream/master -- cgit v1.2.3 From c94c39bf9cc6a5c0fd9207046e8feb8b9a917447 Mon Sep 17 00:00:00 2001 From: David Glick Date: Thu, 12 Feb 2015 21:16:43 -0800 Subject: fix instructions for running coverage via tox --- HACKING.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 16c17699c..e104869ec 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -195,7 +195,7 @@ Test Coverage ------------- - The codebase *must* have 100% test statement coverage after each commit. - You can test coverage via ``tox -e coverage``, or alternately by installing + You can test coverage via ``tox -e cover``, or alternately by installing ``nose`` and ``coverage`` into your virtualenv (easiest via ``setup.py dev``) , and running ``setup.py nosetests --with-coverage``. -- cgit v1.2.3 From 109b2a0b29e0d63a521a91021c736851248ac7d3 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 13 Apr 2015 10:43:21 -0400 Subject: make it possible to run scaffold functests using tox --- HACKING.txt | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index e104869ec..91366cc28 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -191,6 +191,13 @@ Running Tests $ $VENV/bin/easy_install pytest $ py.test --strict pyramid/ +- Functional tests related to the "scaffolds" (starter, zodb, alchemy) which + create a virtualenv, install the scaffold package and its dependencies, start + a server, and hit a URL on the server can be run like so: + + $ tox py2-scaffolds + $ tox py3-scaffolds + Test Coverage ------------- -- cgit v1.2.3 From aa1c9b70369b011856c3b84e288975c1d121d439 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 13 Apr 2015 11:46:50 -0400 Subject: change releasing and hacking docs to reflect new order of using tox to test docs and scaffolds --- HACKING.txt | 52 ++++++++++++++++++++-------------------------------- 1 file changed, 20 insertions(+), 32 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 91366cc28..9a7df8679 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -178,7 +178,7 @@ Running Tests invoke the ``tox`` console script. This will read the ``tox.ini`` file and execute the tests on multiple Python versions and platforms; while it runs, it creates a virtualenv for each version/platform combination. For - example: + example:: $ sudo /usr/bin/easy_install tox $ cd ~/hack-on-pyramid/ @@ -186,25 +186,27 @@ Running Tests - The tests can also be run using ``pytest`` (http://pytest.org/). This is intended as a convenience for people who are more used or fond of ``pytest``. - Run the tests like so: + Run the tests like so:: $ $VENV/bin/easy_install pytest $ py.test --strict pyramid/ - Functional tests related to the "scaffolds" (starter, zodb, alchemy) which create a virtualenv, install the scaffold package and its dependencies, start - a server, and hit a URL on the server can be run like so: + a server, and hit a URL on the server can be run like so:: - $ tox py2-scaffolds - $ tox py3-scaffolds + $ ./scaffoldtests.sh + + Alternately:: + + $ tox -e{py26,py27,py32,py33,py34,pypy,pypy3}-scaffolds, Test Coverage ------------- -- The codebase *must* have 100% test statement coverage after each commit. - You can test coverage via ``tox -e cover``, or alternately by installing - ``nose`` and ``coverage`` into your virtualenv (easiest via ``setup.py - dev``) , and running ``setup.py nosetests --with-coverage``. +- The codebase *must* have 100% test statement coverage after each commit. You + can test coverage via ``./coverage.sh`` (which itself just executes ``tox + -epy2-cover,py3-cover,coverage``). Documentation Coverage and Building HTML Documentation ------------------------------------------------------ @@ -212,45 +214,31 @@ Documentation Coverage and Building HTML Documentation If you fix a bug, and the bug requires an API or behavior modification, all documentation in this package which references that API or behavior must be changed to reflect the bug fix, ideally in the same commit that fixes the bug -or adds the feature. - -To build and review docs (where ``$VENV`` refers to the virtualenv you're -using to develop Pyramid): +or adds the feature. To build and review docs, use the following steps. -1. After following the steps above in "Using a Development Checkout", install - Sphinx and all development requirements in your virtualenv: - - $ cd ~/hack-on-pyramid - $ $VENV/bin/python setup.py docs - -2. Update all git submodules from the top-level of your Pyramid checkout, like - so: +1. After following the steps above in "Using a Development Checkout", update + all git submodules from the top-level of your Pyramid checkout, like so: $ git submodule update --init --recursive This will checkout theme subrepositories and prevent error conditions when HTML docs are generated. -3. Next change into the submodule's directory and switch to a branch so that +2. Next change into the submodule's directory and switch to a branch so that the submodule repositories are no longer "headless". Then update the repository to ensure that we have the latest updates. - See http://chrisjean.com/2009/04/20/git-submodules-adding-using-removing-and-updating/ + See http://chrisjean.com/2009/04/20/git-submodules-adding-using-removing-and-updating/ :: $ cd docs/_themes $ git checkout master $ git pull -4. Change into the ``docs`` directory within your Pyramid checkout and execute - the ``make`` command with some flags: - - $ cd ~/hack-on-pyramid/pyramid/docs - $ make clean html SPHINXBUILD=$VENV/bin/sphinx-build +3. Change back to the main Pyramid checkout dir and run ``./builddocs`` (which + just turns around and runs ``tox -e py2-docs,py3-docs``):: - The ``SPHINXBUILD=...`` argument tells Sphinx to use the virtualenv Python, - which will have both Sphinx and Pyramid (for API documentation generation) - installed. + $ ./builddocs -5. Open the ``docs/_build/html/index.html`` file to see the resulting HTML +5. Open the ``.tox/_build/html/index.html`` file to see the resulting HTML rendering. Change Log -- cgit v1.2.3 From 5e752cd4c9425c4a7e6df250bb8757e7275b573f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 14 Apr 2015 16:22:35 -0400 Subject: 4 comes after 3 --- HACKING.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 9a7df8679..e31dd8714 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -238,7 +238,7 @@ or adds the feature. To build and review docs, use the following steps. $ ./builddocs -5. Open the ``.tox/_build/html/index.html`` file to see the resulting HTML +4. Open the ``.tox/_build/html/index.html`` file to see the resulting HTML rendering. Change Log -- cgit v1.2.3 From 71d66b84dbd2927e79ebf2512a4bd287b7664b84 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 16 Apr 2015 16:47:23 -0400 Subject: Replace git submodule crap with new pylons-sphinx-themes package goodness. See #1614. --- HACKING.txt | 25 ++++--------------------- 1 file changed, 4 insertions(+), 21 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index e31dd8714..b82041c71 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -216,29 +216,12 @@ documentation in this package which references that API or behavior must be changed to reflect the bug fix, ideally in the same commit that fixes the bug or adds the feature. To build and review docs, use the following steps. -1. After following the steps above in "Using a Development Checkout", update - all git submodules from the top-level of your Pyramid checkout, like so: +1. In the main Pyramid checkout directory, run ``./builddocs.sh`` (which just + turns around and runs ``tox -e py2-docs,py3-docs``):: - $ git submodule update --init --recursive + $ ./builddocs.sh - This will checkout theme subrepositories and prevent error conditions when - HTML docs are generated. - -2. Next change into the submodule's directory and switch to a branch so that - the submodule repositories are no longer "headless". Then update the - repository to ensure that we have the latest updates. - See http://chrisjean.com/2009/04/20/git-submodules-adding-using-removing-and-updating/ :: - - $ cd docs/_themes - $ git checkout master - $ git pull - -3. Change back to the main Pyramid checkout dir and run ``./builddocs`` (which - just turns around and runs ``tox -e py2-docs,py3-docs``):: - - $ ./builddocs - -4. Open the ``.tox/_build/html/index.html`` file to see the resulting HTML +2. Open the ``docs/_build/html/index.html`` file to see the resulting HTML rendering. Change Log -- cgit v1.2.3 From 91dee884e9e4831e73a5d0a5c6a00e1e0f1397d9 Mon Sep 17 00:00:00 2001 From: nharringtonwasatch Date: Thu, 1 Oct 2015 13:52:12 -0400 Subject: wiki2 documentation precisely matches the scaffolding output --- HACKING.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index b82041c71..d0f9a769e 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -189,7 +189,7 @@ Running Tests Run the tests like so:: $ $VENV/bin/easy_install pytest - $ py.test --strict pyramid/ + $ $VENV/bin/py.test --strict pyramid/ - Functional tests related to the "scaffolds" (starter, zodb, alchemy) which create a virtualenv, install the scaffold package and its dependencies, start -- cgit v1.2.3 From a708d359ff123084ea64b2e53c3ad32a74711219 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Wed, 25 Nov 2015 18:52:54 -0600 Subject: remove py2-docs from tox.ini and reorder so coverage is last --- HACKING.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index d0f9a769e..c838fda22 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -217,7 +217,7 @@ changed to reflect the bug fix, ideally in the same commit that fixes the bug or adds the feature. To build and review docs, use the following steps. 1. In the main Pyramid checkout directory, run ``./builddocs.sh`` (which just - turns around and runs ``tox -e py2-docs,py3-docs``):: + turns around and runs ``tox -e docs``):: $ ./builddocs.sh -- cgit v1.2.3 From 169dba5c7aa02db2e48cecff8b8126b767fdf327 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 23 Dec 2015 03:19:58 -0800 Subject: - Add Python compatibility to history, hacking, releasing - Use 1.X for version number --- HACKING.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index c838fda22..5bbdce0c6 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -124,10 +124,10 @@ In order to add a feature to Pyramid: - The feature must be documented in both the API and narrative documentation (in ``docs/``). -- The feature must work fully on the following CPython versions: 2.6, - 2.7, 3.2, and 3.3 on both UNIX and Windows. +- The feature must work fully on the following CPython versions: 2.6, 2.7, 3.2, + 3.3, 3.4, and 3.5 on both UNIX and Windows. -- The feature must work on the latest version of PyPy. +- The feature must work on the latest version of PyPy and PyPy3. - The feature must not cause installation or runtime failure on App Engine. If it doesn't cause installation or runtime failure, but doesn't actually @@ -199,7 +199,7 @@ Running Tests Alternately:: - $ tox -e{py26,py27,py32,py33,py34,pypy,pypy3}-scaffolds, + $ tox -e{py26,py27,py32,py33,py34,py35,pypy,pypy3}-scaffolds, Test Coverage ------------- -- cgit v1.2.3