Permalink
Browse files

#1535 docs on contribution and testing

  • Loading branch information...
1 parent f1f0bb6 commit 5727181cec4847eb723a1ceff45351f708441829 @evildmp evildmp committed Dec 10, 2012
Showing with 101 additions and 33 deletions.
  1. +24 −32 CONTRIBUTING.rst
  2. +1 −0 docs/contributing/contributing.rst
  3. +74 −0 docs/contributing/testing.rst
  4. +2 −1 docs/index.rst
View
@@ -3,9 +3,23 @@ Contributing to django CMS
##########################
Like every open-source project, django CMS is always looking for motivated
-individuals to contribute to its source code.
-However, to ensure the highest code quality and keep the repository nice and
-tidy, everybody has to follow a few rules (nothing major, I promise :) )
+individuals to contribute to its source code. However, to ensure the highest
+code quality and keep the repository nice and tidy, everybody has to follow a
+few rules (nothing major, I promise :) )
+
+
+.. ATTENTION::
+
+ If you think you have discovered a security issue in our code, please report
+ it **privately**, by emailing us at `security@django-cms.org`_.
+
+ Please don't raise it on:
+
+ * IRC
+ * GitHub
+ * either of our email lists
+
+ or in any other public forum until we have had a chance to deal with it.
*********
@@ -84,39 +98,16 @@ This is how you fix a bug or add a feature:
#. `fork`_ us on GitHub.
#. Checkout your fork.
-#. Hack hack hack, test test test, commit commit commit, test again.
+#. *Hack hack hack*, *test test test*, *commit commit commit*, test again.
#. Push to your fork.
#. Open a pull request.
+And at any point in that process, you can add: *discuss discuss discuss*,
+because it's always useful for everyone to pass ideas around and look at thngs
+together.
-Tests
-=====
-
-Having a wide and comprehensive library of unit-tests and integration tests is
-of exceeding importance. Contributing tests is widely regarded as a very
-prestigious contribution (you're making everybody's future work much easier by
-doing so). Good karma for you. Cookie points. Maybe even a beer if we meet in
-person :)
-
-Generally tests should be:
-
-- Unitary (as much as possible). I.E. should test as much as possible only one
- function/method/class. That's the
- very definition of unit tests. Integration tests are interesting too
- obviously, but require more time to maintain since they have a higher
- probability of breaking.
-- Short running. No hard numbers here, but if your one test doubles the time it
- takes for everybody to run them, it's probably an indication that you're doing
- it wrong.
-
-In a similar way to code, pull requests will be reviewed before pulling
-(obviously), and we encourage discussion via code review (everybody learns
-something this way) or IRC discussions.
-
-Running the tests
------------------
-
-To run the tests simply execute ``python setup.py test`` from your shell.
+We have an IRC channel, our `django-cms-developers`_ email list,
+and of course the code reviews mechanism on GitHub - do use them.
**************************
@@ -184,6 +175,7 @@ contribute. All changes there will be automatically sent to the project.
+.. _security@django-cms.org: mailto:security@django-cms.org
.. _fork: http://github.com/divio/django-cms
.. _Sphinx: http://sphinx.pocoo.org/
.. _PEP8: http://www.python.org/dev/peps/pep-0008/
@@ -0,0 +1 @@
+.. include:: ../../CONTRIBUTING.rst
@@ -0,0 +1,74 @@
+#########################
+Running and writing tests
+#########################
+
+Good code needs tests.
+
+A project like django CMS simply can't afford to incorporate new code that
+doesn't come with its own tests.
+
+Tests provide some necessary minimum confidence: they can show the code will
+behave as it expected, and help identify what's going wrong if something breaks
+it.
+
+Not insisting on good tests when code is committed is like letting a gang of
+teenagers without a driving licence borrow your car on a Friday night, even if
+you think they are very nice teenagers and they really promise to be careful.
+
+We certainly do want your contributions and fixes, but we need your tests with
+them too. Otherwise, we'd be compromising our codebase.
+
+So, you are going to have to include tests if you want to contribute. However,
+writing tests is not particularly difficult, and there are plenty of examples to
+crib from in the code to help you.
+
+*************
+Running tests
+*************
+
+There's more than one way to do this, but here's one to help you get started::
+
+ # create a virtual environment
+ virtualenv test-django-cms
+ # activate it
+ cd test-django-cms/
+ source bin/activate
+ # get django CMS from GitHub
+ git clone git@github.com:divio/django-cms.git
+ # install the dependencies for testing
+ # note that requirements files for other Django versions are also provided
+ pip install -r django-cms/test_requirements/django-1.4.txt
+ # run the test suite
+ django-cms/runtests.py
+
+It can take a few minutes to run.
+
+When you run tests against your own new code, don't forget that it's useful to
+repeat them for different versions of Python and Django.
+
+*************
+Writing tests
+*************
+
+Contributing tests is widely regarded as a very prestigious contribution (you're
+making everybody's future work much easier by doing so). Good karma for you.
+Cookie points. Maybe even a beer if we meet in person :)
+
+What we need
+============
+
+We have a wide and comprehensive library of unit-tests and integration tests
+with good coverage.
+
+Generally tests should be:
+
+* Unitary (as much as possible). i.e. should test as much as possible only one
+ function/method/class. That's the very definition of unit tests. Integration
+ tests are interesting too obviously, but require more time to maintain since
+ they have a higher probability of breaking.
+* Short running. No hard numbers here, but if your one test doubles the time it
+ takes for everybody to run them, it's probably an indication that you're doing
+ it wrong.
+* Easy to understand. If your test code isn't obvious, please add comments on
+ what it's doing.
+
View
@@ -102,7 +102,8 @@ Contributing to django CMS
:maxdepth: 2
:numbered:
- contribution
+ contributing/contributing
+ contributing/testing

0 comments on commit 5727181

Please sign in to comment.