Contributing to django CMS

Like every open-source project, django CMS is always looking for motivated individuals to contribute to its source code.

Key points:

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 do not 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.

Community

People interested in developing for the django CMS should join the django-cms-developers mailing list as well as heading over to #django-cms on the freenode IRC network for help and to discuss the development.

You may also be interested in following @djangocmsstatus on twitter to get the GitHub commits as well as the hudson build reports. There is also a @djangocms account for less technical announcements.

In a nutshell

Here’s what the contribution process looks like, in a bullet-points fashion, and only for the stuff we host on GitHub:

  1. django CMS is hosted on GitHub, at https://github.com/divio/django-cms
  2. The best method to contribute back is to create an account there, then fork the project. You can use this fork as if it was your own project, and should push your changes to it.
  3. When you feel your code is good enough for inclusion, “send us a pull request”, by using the nice GitHub web interface.

Contributing Code

Getting the source code

If you’re interested in developing a new feature for the CMS, it is recommended that you first discuss it on the django-cms-developers mailing list so as not to do any work that will not get merged in anyway.

  • Code will be reviewed and tested by at least one core developer, preferably by several. Other community members are welcome to give feedback.
  • Code must be tested. Your pull request should include unit-tests (that cover the piece of code you’re submitting, obviously)
  • Documentation should reflect your changes if relevant. There is nothing worse than invalid documentation.
  • Usually, if unit tests are written, pass, and your change is relevant, then it’ll be merged.

Since we’re hosted on GitHub, django CMS uses git as a version control system.

The GitHub help is very well written and will get you started on using git and GitHub in a jiffy. It is an invaluable resource for newbies and old timers alike.

Syntax and conventions

Python

We try to conform to PEP8 as much as possible. A few highlights:

  • Indentation should be exactly 4 spaces. Not 2, not 6, not 8. 4. Also, tabs are evil.
  • We try (loosely) to keep the line length at 79 characters. Generally the rule is “it should look good in a terminal-base editor” (eg vim), but we try not be [Godwin’s law] about it.

HTML, CSS and JavaScript

As of django CMS 3.2, we are using the same guidelines as described in Aldryn Boilerplate

Frontend code should be formatted for readability. If in doubt, follow existing examples, or ask.

JS Linting

JavaScript is linted using JSHint and JSCS. In order to run the linters you need to do this:

gulp lint

Or you can also run the watcher by just running gulp.

JS Bundling

Javascript files are split up for easier development, but in the end they are bundled together and minified to decrease amount of requests made and improve performance. In order to do that we use gulp task runner, where bundle command is available. Configuration and list of dependencies for each bundle are stored inside the gulpfile.js.

Process

This is how you fix a bug or add a feature:

  1. fork us on GitHub.
  2. Checkout your fork.
  3. Hack hack hack, test test test, commit commit commit, test again.
  4. Push to your fork.
  5. 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 things together.

Running and writing tests is really important: a pull request that lowers our testing coverage will only be accepted with a very good reason; bug-fixing patches must demonstrate the bug with a test to avoid regressions and to check that the fix works.

We have an IRC channel, our django-cms-developers email list, and of course the code reviews mechanism on GitHub - do use them.

Contributing Documentation

Perhaps considered “boring” by hard-core coders, documentation is sometimes even more important than code! This is what brings fresh blood to a project, and serves as a reference for old timers. On top of this, documentation is the one area where less technical people can help most - you just need to write simple, unfussy English. Elegance of style is a secondary consideration, and your prose can be improved later if necessary.

Documentation should be:

  • written using valid Sphinx/restructuredText syntax (see below for specifics); the file extension should be .rst
  • wrapped at 100 characters per line
  • written in English, using British English spelling and punctuation
  • accessible - you should assume the reader to be moderately familiar with Python and Django, but not anything else. Link to documentation of libraries you use, for example, even if they are “obvious” to you

Merging documentation is pretty fast and painless.

Also, contributing to the documentation will earn you great respect from the core developers. You get good karma just like a test contributor, but you get double cookie points. Seriously. You rock.

Except for the tiniest of change, we recommend that you test them before submitting. Follow the same steps above to fork and clone the project locally. Next, create a virtualenv so you can install the documentation tools:

virtualenv djcms-docs-env
source djcms-docs-env/bin/activate
pip install sphinx sphinx_rtd_theme

Now you can cd into the django-cms/docs directory and build the documentation:

make html
open build/html/index.html

This allows you to review your changes in your local browser. After each change, be sure to rebuild the docs using make html. If everything looks good, then it’s time to push your changes to Github and open a pull request.

Documentation structure

Our documentation is divided into the following main sections:

Documentation markup

Sections

We mostly follow the Python documentation conventions for section marking:

##########
Page title
##########

*******
heading
*******

sub-heading
===========

sub-sub-heading
---------------

sub-sub-sub-heading
^^^^^^^^^^^^^^^^^^^

sub-sub-sub-sub-heading
"""""""""""""""""""""""

Inline markup

  • use backticks - `` - for:
    • literals:

      The ``cms.models.pagemodel`` contains several important methods.
      
    • filenames:

      Before you start, edit ``settings.py``.
      
    • names of fields and other specific items in the Admin interface:

      Edit the ``Redirect`` field.
      
  • use emphasis - *Home* - around:
    • the names of available options in or parts of the Admin:

      To hide and show the *Toolbar*, use the...
      
    • the names of important modes or states:

      ... in order to switch to *Edit mode*.
      
    • values in or of fields:

      Enter *Home* in the field.
      
  • use strong emphasis - ** - around:
    • buttons that perform an action:

      Hit **Save as draft**.
      

Rules for using technical words

There should be one consistent way of rendering any technical word, depending on its context. Please follow these rules:

  • in general use, simply use the word as if it were any ordinary word, with no capitalisation or highlighting: “Your placeholder can now be used.”
  • at the start of sentences or titles, capitalise in the usual way: “Placeholder management guide”
  • when introducing the term for the the first time, or for the first time in a document, you may highlight it to draw attention to it: “Placeholders are special model fields”.
  • when the word refers specifically to an object in the code, highlight it as a literal: “Placeholder methods can be overwritten as required” - when appropriate, link the term to further reference documentation as well as simply highlighting it.

References

Create:

.. _testing:

and use:

:ref:`testing`

internal cross-references liberally.

Use absolute links to other documentation pages - :doc:`/how_to/toolbar` - rather than relative links - :doc:`/../toolbar`. This makes it easier to run search-and-replaces when items are moved in the structure.

Translations

For translators we have a Transifex account where you can translate the .po files and don’t need to install git or mercurial to be able to contribute. All changes there will be automatically sent to the project.

Top translations django-cms core:

Frontend

In order to be able to work with the frontend tooling contributing to the django CMS you need to have the following dependencies installed:

  1. Node (will install npm as well).
  2. Globally installed gulp
  3. Local dependencies npm install

Styles

We are using Sass for our styles. The files are located within cms/static/cms/sass and can be compiled using the libsass implementation of Sass compiler through Gulp.

In order to compile the stylesheets you need to run this command from the repo root:

gulp sass

While developing it is also possible to run a watcher that compiles Sass files on change:

gulp

By default, sourcemaps are not included in the compiled files. In order to turn them on while developing just add the --debug option:

gulp --debug

Icons

We are using gulp-iconfont to generate icon webfonts into cms/static/cms/fonts/. This also creates _iconography.scss within cms/static/cms/sass/components which adds all the icon classes and ultimately compiles to css.

In order to compile the webfont you need to run:

gulp icons

This simply takes all SVGs within cms/static/cms/fonts/src and embeds them into the webfont. All classes will be automatically added to _iconography.scss as previously mentioned.

Additionally we created an SVG template within cms/static/cms/font/src/_template.svgz that you should use when converting or creating additional icons. It is named svgz so it doesn’t get compiled into the font. When using Adobe Illustrator please mind the following settings.