Contributing

Note

The topics of this chapter is covered in more details into the Contributing to django CMS and Running and writing tests sections of the documentation

django CMS is an open source and open project which welcomes anyone who want to provide its contribution at any level of knowledge.

You can contribute code, documentation and translations.

Starting contributing code

Before actually coding anything, please read the guidelines and the policies regulating the django CMS project development. Adhering to them will make much easier for the core developers to validate and accept your contribution.

The basic step to contribute are:

  1. fork django CMS project repostory on github

  2. clone your fork on your local computer:

    1. git clone git@github.com:YOUR_USERNAME/django-cms.git

  3. create a virtualenv:

    1. virtualenv cms-develop
    2. source cms-develop/bin/activate

  4. install the dependencies:

    1. cd django-cms
    2. pip install -r test_requirements/django-1.7.txt

    or whichever Django version you target

  5. code you contribution

  6. run the tests:

    1. python develop.py test

  7. commit and push your code into a feature branch:

    1. git checkout -b my_fix
    2. git commit
    3. git push origin my_fix

  8. open a pull request on github

Target branches

At one point in time django CMS project will have at least two active branches:

  • latest support/version.x which you sholud target if you submit bugfixes for version.x
  • develop for new features and bugfixes for latest version if a corresponding support/version.y does not exists (yet)

How to write a test

django CMS test suite contains a mix of unit tests, functional tests, regression tests and integration tests.

Depending on your contribution, you will write a mix of them.

Let’s start with something simple.

Let’s say you want to test the behavior of CMSPluginBase.render method:

  1. class CMSPluginBase(six.with_metaclass(CMSPluginBaseMetaclass, admin.ModelAdmin)):
  3.     ...
  5.     def render(self, context, instance, placeholder):
  6.         context['instance'] = instance
  7.         context['placeholder'] = placeholder
  8.         return context

Writing a unit test for it will require us to test whether the return context object contains the declared attributes with the correct values.

We will start with a new class in an existing django CMS test module (cms.tests.plugins in this case):

  1. class SimplePluginTestCase(CMSTestCase):
  2.     pass

Let’s try to run it (given you’ve setup correctly your environment as in start-contributing:

  1. python develop.py test cms.SimplePluginTestCase

This will call the new test case class only and it’s hany when creating new tests and iterating quickly throught the steps. A full test run (python develop.py test) is required before opening a pull request.

This is the output you’ll get:

  1. Creating test database for alias 'default'...
  3. ----------------------------------------------------------------------
  4. Ran 0 tests in 0.000s
  6. OK

Which is correct as we have no test in our test case. Let’s add and (empty) one:

  1. class SimplePluginTestCase(CMSTestCase):
  3.     def test_render_method(self):
  4.         pass

Running the test command again will return a sighltly different output:

  1. Creating test database for alias 'default'...
  2. .
  3. ----------------------------------------------------------------------
  4. Ran 1 test in 0.001s
  6. OK

This looks better, but it’s not that meaningful as we’re not testing anything.

Write a real test:

  1. class SimplePluginTestCase(CMSTestCase):
  3.     def test_render_method(self):
  4.         """
  5.         Tests the CMSPluginBase.render method by checking that the appropriate variables
  6.         are set in the returned context
  7.         """
  8.         from cms.api import create_page
  9.         my_page = create_page('home', language='en', template='col_two.html')
  10.         placeholder = my_page.placeholders.get(slot='col_left')
  11.         context = self.get_context('/', page=my_page)
  12.         plugin = CMSPluginBase()
  14.         new_context = plugin.render(context, None, placeholder)
  15.         self.assertTrue('placeholder' in new_context)
  16.         self.assertEqual(placeholder, context['placeholder'])
  17.         self.assertTrue('instance' in new_context)
  18.         self.assertIsNone(new_context['instance'])

and run it:

  1. Creating test database for alias 'default'...
  2. .
  3. ----------------------------------------------------------------------
  4. Ran 1 test in 0.044s
  6. OK

Output is quite similar than the previous run, only the longer execution time gives us a hint that this test is actually doing something.

Let’s quickly check the test code.

To test CMSPluginBase.render method we need a RequestContext instance and a placeholder. As CMSPluginBase does not have any configuration model, the instance argument can be None.

  1. Create a page instance to get the placeholder
  2. Get the placeholder by filtering the placeholders of the page instance on the expected placeholder name
  3. Create a context instance by using the provided super class method
  4. Call the render method on a CMSPluginBase instance; being stateless, it’s easy to call render of a bare instance of the CMSPluginBase class, which helps in tests
  5. Assert a few things the method must provide on the returned context instance

As you see, even a simple test like this assumes and uses many feature of the test utils provided by django CMS. Before attempting to write a test, take your time to explore the content of cms.test_utils package and check the shipped templates, example applications and, most of all, the base testcases defined in cms.test_utils.testscases which provide a lot of useful methods to prepare the environment for our tests or to create useful test data.

Submitting your code

After the code and the tests are ready and packed in commits, you must submit it for review and merge in the django CMS github project.

As stated above, always create a feature branch for your code, being it a fix or a new feature; then you can create a Pull Request from your branch to the target branch on django CMS.

Acceptance criteria

Matching this criteria from the very beginning will help the core developers to be able to review your submission more quickly and efficiently and will greatly help your code to be merged in.

Features

To be accepted, proposed features should have at least:

  • natural language documentation in the docs folder describing the feature, its usage and potentially backward incompatibilities.
  • inline documentation (comments and docstrings) in the critical areas of the code explaining the behavior
  • appropriate test coverage
  • Python 2/3 compatibility
  • South and Django migrations (where applicable)

The pull request description must briefly describe the feature and the intended goal and benefits.

Bugs

To be accepted, proposed bug fixes should have at least:

  • inline documentation (comments and docstrings) in the critical areas of the code explaining the behavior
  • at least 1 regression test that demonstrates the issue and the fix
  • Python 2/3 compatibility
  • South and Django migrations (where applicable)

The pull request description must briefly describe the bug and the steps for its solution; in case the bug has been opened elsewhere, it must be linked in the Pull Request description, describing the fix.