Contributing to Zotonic

Emacs

Provided with the Zotonic distribution is a Zotonic template mode, zotonic-tpl-mode, which supports the Zotonic flavor of Django. It is located in the priv/emacs/zotonic-tpl-mode.el file, and may be installed in emacs by adding something like this to your .emacs file:

(add-to-list 'load-path ".../path/to/zotonic/priv/emacs")
(require 'zotonic-tpl-mode)
;; optional, for associating .tpl files with zotonic-tpl-mode
(add-to-list 'auto-mode-alist '("\\.tpl$" . zotonic-tpl-mode))

Build the documentation

First, install Sphinx. To build the documentation, Erlang must be installed.

$ cd doc/

# Install dependencies
$ pip install -r requirements.txt

# Generate meta-*.rst files:
$ make stubs

# Then generate HTML files:
$ make html

Then view the HTML files in doc/_build/html/index.html.

Heading styles

Use the following convention for headings:

First-level heading
===================

Second-level heading
--------------------

Third-level heading
^^^^^^^^^^^^^^^^^^^

Fourth-level heading
""""""""""""""""""""

When writing documentation of modules, actions, etc.; anything under ref/; the first level heading is already there for you, generated in the meta-*.rst file. So you should only use ---------- and .......... for the headings in the ref/ files.

When using Emacs, this little snippet helps with adding underlines to headings:

(defun underline-with-char (char)
  (interactive (list (read-from-minibuffer "Char: ")))
  (when (= 0 (length char))
    (error "Need a character"))
  (setq char (aref char 0))             ; Ignore everything but the first char.
  (save-excursion
    (goto-char (point-at-eol))
    (insert "\n"
            (make-string (- (point-at-eol)
                            (point-at-bol))
                         char))))

From a mailing list post.

References

Be generous with using references (:ref:`pagelabel`) in your writing. The more terms are linked to their respective documentation pages, the better. Only make the first occurrence of a term a reference to its page, though; consequent occurrences can be made `italic`.

Add a .. seealso:: section at the top to highlight any other pages which are closely related to the current one, for example:

.. code-block:: none

Table styles

For the easy editing of tables, we use Emacs’ table-mode, which at first has a bit of a learning curve but actually works pretty well when creating the ascii-art tables that the RST format requires you to use.

In general, we use this style of table:

+--------------------+-------------------+
| Header             |Other header       |
+====================+===================+
|This is the table   |Some more contents |
|cell contents       |                   |
+--------------------+-------------------+

Release dates

Zotonic follows a time-based release model. Every first Monday of the month – at the call of the Dutch test siren – a new Zotonic version is released. Version numbers are incremented according to the Semantic versioning specification.

Release schedule

Preparation for each release lasts one month:

1. Development phase: new features are added and existing ones improved. Commits take place on the current .x development branch (for instance, 0.x).
2. Stabilisation phase: five working days before a release, we create a release branch from the development branch, incrementing the minor version number (for instance, release-0.16.0). During the stabilisation phase, no new features are added. Instead, the last bug fixes for the release are committed.
3. On the first Monday of each month, the release branch is tagged (for instance, 0.16.0), merged back into the development branch and then discarded.

Hotfix releases

Some bug fixes, such as security fixes, need to be made available immediately. In case a change cannot wait for the next monthly release, we release it as a hotfix, incrementing the patch number (for instance, 0.16.1).