Add hacking docs.

2 files changed, 370 insertions, 0 deletions

diff --git a/docs/hacking.rst b/docs/hacking.rst
new file mode 100644
index 0000000..c91f54f
--- /dev/null
+++ b/docs/hacking.rst
@@ -0,0 +1,369 @@
+Hacking on :mod:`zope.security`
+===============================
+
+
+Getting the Code
+################
+
+The main repository for :mod:`zope.security` is in the Zope Foundation
+Github repository:
+
+  https://github.com/zopefoundation/zope.security
+
+You can get a read-only checkout from there:
+
+.. code-block:: sh
+
+   $ git clone https://github.com/zopefoundation/zope.security.git
+
+or fork it and get a writeable checkout of your fork:
+
+.. code-block:: sh
+
+   $ git clone git@github.com/jrandom/zope.security.git
+
+The project also mirrors the trunk from the Github repository as a
+Bazaar branch on Launchpad:
+
+https://code.launchpad.net/zope.security
+
+You can branch the trunk from there using Bazaar:
+
+.. code-block:: sh
+
+   $ bzr branch lp:zope.security
+
+
+Working in a ``virtualenv``
+###########################
+
+Installing
+----------
+
+If you use the ``virtualenv`` package to create lightweight Python
+development environments, you can run the tests using nothing more
+than the ``python`` binary in a virtualenv.  First, create a scratch
+environment:
+
+.. code-block:: sh
+
+   $ /path/to/virtualenv --no-site-packages /tmp/hack-zope.security
+
+Next, get this package registered as a "development egg" in the
+environment:
+
+.. code-block:: sh
+
+   $ /tmp/hack-zope.security/bin/python setup.py develop
+
+Running the tests
+-----------------
+
+Then, you canrun the tests using the build-in ``setuptools`` testrunner:
+
+.. code-block:: sh
+
+   $ /tmp/hack-zope.security/bin/python setup.py test
+   ...................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
+   ----------------------------------------------------------------------
+   Ran 643 tests in 0.000s
+
+   OK
+
+If you have the :mod:`nose` package installed in the virtualenv, you can
+use its testrunner too:
+
+.. code-block:: sh
+
+   $ /tmp/hack-zope.security/bin/easy_install nose
+   ...
+   $ /tmp/hack-zope.security/bin/nosetests
+   ...............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
+   ----------------------------------------------------------------------
+   Ran 655 tests in 0.000s
+
+   OK
+
+If you have the :mod:`coverage` pacakge installed in the virtualenv,
+you can see how well the tests cover the code:
+
+.. code-block:: sh
+
+   $ /tmp/hack-zope.security/bin/easy_install nose coverage
+   ...
+   $ /tmp/hack-zope.security/bin/nosetests --with coverage
+   ...............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
+   Name                              Stmts   Miss  Cover   Missing
+   ---------------------------------------------------------------
+   zope/security.py                      4      0   100%   
+   zope/security/_compat.py              9      0   100%   
+   zope/security/_definitions.py        11      0   100%   
+   zope/security/adapter.py             45      0   100%   
+   zope/security/checker.py            333      0   100%   
+   zope/security/decorator.py           33      0   100%   
+   zope/security/i18n.py                 4      0   100%   
+   zope/security/interfaces.py          65      0   100%   
+   zope/security/management.py          62      0   100%   
+   zope/security/metaconfigure.py      108      0   100%   
+   zope/security/metadirectives.py      38      0   100%   
+   zope/security/permission.py          46      0   100%   
+   zope/security/protectclass.py        39      0   100%   
+   zope/security/proxy.py              164     19    88%   55, 86, 97, 119-121, 127-129, 143-144, 153-154, 158-159, 163-164, 298, 330
+   zope/security/simplepolicies.py      32      0   100%   
+   zope/security/zcml.py                43      0   100%   
+   ---------------------------------------------------------------
+   TOTAL                              1036     19    98%   
+   ----------------------------------------------------------------------
+   Ran 655 tests in 0.000s
+
+   OK
+
+
+Building the documentation
+--------------------------
+
+:mod:`zope.security` uses the nifty :mod:`Sphinx` documentation system
+for building its docs.  Using the same virtualenv you set up to run the
+tests, you can build the docs:
+
+.. code-block:: sh
+
+   $ /tmp/hack-zope.security/bin/easy_install Sphinx
+   ...
+   $ cd docs
+   $ PATH=/tmp/hack-zope.security/bin:$PATH make html
+   sphinx-build -b html -d _build/doctrees   . _build/html
+   ...
+   build succeeded.
+
+   Build finished. The HTML pages are in _build/html.
+
+You can also test the code snippets in the documentation:
+
+.. code-block:: sh
+
+   $ PATH=/tmp/hack-zope.security/bin:$PATH make doctest
+   sphinx-build -b doctest -d _build/doctrees   . _build/doctest
+   ...
+   running tests...
+
+   Document: api/zcml
+   ------------------
+   1 items passed all tests:
+     23 tests in default
+   23 tests in 1 items.
+   23 passed and 0 failed.
+   Test passed.
+
+   Document: api/proxy
+   -------------------
+   1 items passed all tests:
+     11 tests in default
+   11 tests in 1 items.
+   11 passed and 0 failed.
+   Test passed.
+   1 items passed all tests:
+      1 tests in default (cleanup code)
+   1 tests in 1 items.
+   1 passed and 0 failed.
+   Test passed.
+
+   Document: api/permission
+   ------------------------
+   1 items passed all tests:
+     35 tests in default
+   35 tests in 1 items.
+   35 passed and 0 failed.
+   Test passed.
+   1 items passed all tests:
+      1 tests in default (cleanup code)
+   1 tests in 1 items.
+   1 passed and 0 failed.
+   Test passed.
+
+   Document: api/checker
+   ---------------------
+   1 items passed all tests:
+    356 tests in default
+   356 tests in 1 items.
+   356 passed and 0 failed.
+   Test passed.
+
+   Document: api/decorator
+   -----------------------
+   1 items passed all tests:
+     53 tests in default
+   53 tests in 1 items.
+   53 passed and 0 failed.
+   Test passed.
+   1 items passed all tests:
+      1 tests in default (cleanup code)
+   1 tests in 1 items.
+   1 passed and 0 failed.
+   Test passed.
+
+   Doctest summary
+   ===============
+     478 tests
+       0 failures in tests
+       0 failures in setup code
+       0 failures in cleanup code
+
+
+Using :mod:`zc.buildout`
+########################
+
+Setting up the buildout
+-----------------------
+
+:mod:`zope.security` ships with its own :file:`buildout.cfg` file and
+:file:`bootstrap.py` for setting up a development buildout:
+
+.. code-block:: sh
+
+   $ /path/to/python2.6 bootstrap.py
+   ...
+   Generated script '.../bin/buildout'
+   $ bin/buildout
+   Develop: '/home/jrandom/projects/Zope/BTK/security/.'
+   ...
+
+Running the tests
+-----------------
+
+You can now run the tests:
+
+.. code-block:: sh
+
+   $ bin/test --all
+   Running zope.testing.testrunner.layer.UnitTests tests:
+     Set up zope.testing.testrunner.layer.UnitTests in 0.000 seconds.
+     Ran 643 tests with 0 failures and 0 errors in 0.000 seconds.
+   Tearing down left over layers:
+     Tear down zope.testing.testrunner.layer.UnitTests in 0.000 seconds.
+
+
+
+Using :mod:`tox`
+################
+
+Running Tests on Multiple Python Versions
+-----------------------------------------
+
+`tox <http://tox.testrun.org/latest/>`_ is a Python-based test automation
+tool designed to run tests against multiple Python versions.  It creates
+a ``virtualenv`` for each configured version, installs the current package
+and configured dependencies into each ``virtualenv``, and then runs the
+configured commands.
+   
+:mod:`zope.security` configures the following :mod:`tox` environments via
+its ``tox.ini`` file:
+
+- The ``py26``, ``py27``, ``py33``, ``py34``, and ``pypy`` environments
+  builds a ``virtualenv`` with the appropriate interpreter,
+  installs :mod:`zope.security` and dependencies, and runs the tests
+  via ``python setup.py test -q``.
+
+- The ``py27-pure`` and ``py33-pure`` environments build a ``virtualenv``
+  with the appropriate interpreter, installs :mod:`zope.security` and
+  dependencies **without compiling C extensions**, and runs the tests
+  via ``python setup.py test -q``.
+
+- The ``coverage`` environment builds a ``virtualenv`` with ``python2.6``,
+  installs :mod:`zope.security`, installs
+  :mod:`nose` and :mod:`coverage`, and runs ``nosetests`` with statement
+  coverage.
+
+- The ``docs`` environment builds a virtualenv with ``python2.6``, installs
+  :mod:`zope.security`, installs ``Sphinx`` and
+  dependencies, and then builds the docs and exercises the doctest snippets.
+
+This example requires that you have a working ``python2.6`` on your path,
+as well as installing ``tox``:
+
+.. code-block:: sh
+
+   $ tox -e py26
+   GLOB sdist-make: .../zope.security/setup.py
+   py26 sdist-reinst: .../zope.security/.tox/dist/zope.security-4.0.2dev.zip
+   py26 runtests: commands[0]
+   ...................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
+   ----------------------------------------------------------------------
+   Ran 643 tests in 0.000s
+
+   OK
+   ___________________________________ summary ____________________________________
+   py26: commands succeeded
+   congratulations :)
+
+Running ``tox`` with no arguments runs all the configured environments,
+including building the docs and testing their snippets:
+
+.. code-block:: sh
+
+   $ tox
+   GLOB sdist-make: .../zope.security/setup.py
+   py26 sdist-reinst: .../zope.security/.tox/dist/zope.security-4.0.2dev.zip
+   py26 runtests: commands[0]
+   ...
+   Doctest summary
+   ===============
+    478 tests
+      0 failures in tests
+      0 failures in setup code
+      0 failures in cleanup code
+   build succeeded.
+   ___________________________________ summary ____________________________________
+   py26: commands succeeded
+   py27: commands succeeded
+   py27-pure: commands succeeded
+   pypy: commands succeeded
+   py32: commands succeeded
+   py33: commands succeeded
+   py33-pure: commands succeeded
+   py34: commands succeeded
+   coverage: commands succeeded
+   docs: commands succeeded
+   congratulations :)
+
+
+Contributing to :mod:`zope.security`
+####################################
+
+Submitting a Bug Report
+-----------------------
+
+:mod:`zope.security` tracks its bugs on Github:
+
+  https://github.com/zopefoundation/zope.security/issues
+
+Please submit bug reports and feature requests there.
+
+
+Sharing Your Changes
+--------------------
+
+.. note::
+
+   Please ensure that all tests are passing before you submit your code.
+   If possible, your submission should include new tests for new features
+   or bug fixes, although it is possible that you may have tested your
+   new code by updating existing tests.
+
+If have made a change you would like to share, the best route is to fork
+the Githb repository, check out your fork, make your changes on a branch
+in your fork, and push it.  You can then submit a pull request from your
+branch:
+
+  https://github.com/zopefoundation/zope.security/pulls
+
+If you branched the code from Launchpad using Bazaar, you have another
+option:  you can "push" your branch to Launchpad:
+
+.. code-block:: sh
+
+   $ bzr push lp:~jrandom/zope.security/cool_feature
+
+After pushing your branch, you can link it to a bug report on Github,
+or request that the maintainers merge your branch using the Launchpad
+"merge request" feature.
diff --git a/docs/index.rst b/docs/index.rst
index f7c9d0d..f6418b6 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -8,6 +8,7 @@ Narrative Documentation
    :maxdepth: 2
 
    narr
+   hacking
 
 API Reference
 -------------