Updated development-related documentation. (#5290)

* Updated contributor notes in README
* Updated list of core developers
* Updated branch policy
* Added commit and changelog policies
* Fixed some spelling and minor other issues

CHANGELOG.txt

@@ -1,5 +1,6 @@
 === 3.2.6 (unreleased) ===
 
+- Added contribution policies documentation
 - Adds CMS_WIZARD_CONTENT_PLACEHOLDER setting
 - Renames the CMS_WIZARD_* settings to CMS_PAGE_WIZARD_*
 - Deprecates the old-style wizard-related settings

README.rst

@@ -15,50 +15,40 @@ django CMS
    :target: https://codeclimate.com/github/divio/django-cms
    :alt: Code Climate
 
-Open source enterprise content management system based on the django framework.
+Open source enterprise content management system based on the Django framework.
 
 .. image:: https://raw.githubusercontent.com/divio/django-cms/develop/docs/images/try-with-aldryn.png
    :target: http://demo.django-cms.org/
    :alt: Try demo with Aldryn
 
-.. ATTENTION:: To propose features, always open pull requests on the **develop** branch.
-   It's the branch for features that will go into the next django CMS feature release.
+.. ATTENTION::
 
-   For fixes for 3.1.x releases, please work on **support/3.1.x** which contains
-   the next patch release for 3.1.x series.
+    To propose **significant new features**, open pull requests based on and made against the **develop** branch. It's
+    the branch for features that will go into the next django CMS feature release.
 
-   For fixes for 3.0.x releases, please work on **support/3.0.x** which contains
-   the next patch release for 3.0.x series.
+    To propose **fixes and backwards-compatible improvements**, please work on the latest **release** branch. This is
+    the branch that will become the next PyPI release ("the next version of django CMS").
 
-   The **master** branch is the current stable release, the one released on PyPI.
-   Changes based on **master** will not be accepted.
+    Security fixes will be backported to older branches by the core team as appropriate.
 
 
 ********
 Features
 ********
 
-* Hierarchical pages
-* Extensive support for multilingual websites
-* Multi site support
-* Draft/Published workflows
-* Undo/Redo
-* Use the content blocks (placeholders) in your own apps (models)
-* Use the content blocks (static placeholders) anywhere in your templates
-* Edit content directly in the frontend on your pages
-* Hierarchical content plugins (columns, style changes etc)
-* Navigation rendering and extending from your apps
-* SEO friendly URLs
-* Highly integrative into your own apps
-
-
-You can define editable areas, called placeholders, in your templates which you fill
-with many different so called CMS content plugins.
-A list of all the plugins can be found here:
-
-`3rd party plugins <http://www.djangopackages.com/grids/g/django-cms/>`_
-
-Should you be unable to find a suitable plugin for you needs, writing your own is very simple.
+* hierarchical pages
+* extensive built-in support for multilingual websites
+* multi-site support
+* draft/publish workflows
+* version control
+* a sophisticated publishing architecture, that's also usable in your own applications
+* frontend content editing
+* a hierarchical content structure for nested plugins
+* an extensible navigation system that your own applications can hook into
+* SEO-friendly URLs
+* designed to integrate thoroughly into other applications
+
+Developing applications that integrate with and take advantage of django CMS features is easy and well-documented.
 
 More information on `our website <http://www.django-cms.org>`_.
 

docs/contributing/code.rst

@@ -129,6 +129,14 @@ If you don't have an IRC client, you can `join our IRC channel using the KiwiIRC
 Frontend
 ********
 
+..  important::
+
+    When we refer to the *frontend* here, we **only** mean the frontend of django CMS's admin/editor interface.
+
+    The frontend of a django CMS website, as seen by its visitors (i.e. the published site), is *wholly independent of
+    this*. django CMS places almost no restrictions at all on the frontend - if a site can be described in
+    HTML/CSS/JavaScript, it can be developed in django CMS.
+
 In order to be able to work with the frontend tooling contributing to the
 django CMS you need to have the following dependencies installed:
 
@@ -139,7 +147,7 @@ django CMS you need to have the following dependencies installed:
 Styles
 ======
 
-We are using `Sass <http://sass-lang.com/>`_ for our styles. The files
+We use `Sass <http://sass-lang.com/>`_ for our styles. The files
 are located within ``cms/static/cms/sass`` and can be compiled using the
 `libsass <http://libsass.org/>`_ implementation of Sass compiler through
 `Gulp <http://gulpjs.com/>`_.

docs/contributing/development.rst

@@ -97,6 +97,15 @@ Current core developers
 * Vadim Sikora https://github.com/vxsx
 
 
+Core designers
+--------------
+
+django CMS also receives important contributions from *core designers*, responsible for key aspects of its visual
+design:
+
+* Christian Bertschy
+* Matthias Nüesch
+
 Retired core developers
 =======================
 

docs/contributing/index.rst

@@ -71,11 +71,16 @@ Security issues
         or in any other public forum until we have had a chance to deal with it.
 
 
-*************************
+.. _development_policies:
+
+********************
+Development policies
+********************
+
 Release schedule & policy
-*************************
+=========================
 
-The roadmap <https://github.com/divio/django-cms/wiki/Roadmap>`_ can be found on our GitHub wiki
+The `roadmap <https://github.com/divio/django-cms/wiki/Roadmap>`_ can be found on our GitHub wiki
 page.
 
 We are planning releases according to **key principles and aims**. Issues within milestones are
@@ -89,19 +94,132 @@ versions are maintained through the community. Divio provides long term support
 `commercial support <http://divio.ch/en/commercial-support/>`_.
 
 
-*************
+.. _branch_policy:
+
 Branch policy
-*************
+=============
+
+.. versionchanged:: 3.3
+
+We maintain a number of branches on `our GitHub repository <https://github.com/divio/django-cms>`_.
+
+the latest (highest-numbered) ``release/x.y.z``
+    This is the branch that will become the next release on PyPI.
 
-* **master**: this is the current stable release, the version released on PyPI.
-* **support/3.2.x**: this will be our *next stable release*; this is the most
-  appropriate branch for fixes and patches that will go into the next **master**
-* **develop**: this will be *django CMS 3.3*; this is the most appropriate
-  branch for more substantial features that will need team co-ordination
+    **Fixes and backwards-compatible improvements** (i.e. most pull requests) will be made against
+    this branch.
 
-If in doubt, ask on the #django-cms IRC channel on `freenode`_ or the
+``develop``
+    This is the branch that will become the next release that increments the ``x`` or ``y`` of the latest
+    ``release/x.y.z``.
+
+    This branch is for **new features and backwards-incompatible changes**. By their nature, these will require more
+    substantial team co-ordination.
+
+Older ``release/x.y.z`` branches
+     These represent the final point of development (the highest ``y`` of older versions). Releases in the full set of
+     older versions have been tagged (use Git Tags to retrieve them).
+
+     These branches will only rarely be patched, with security fixes representing the main reason for a patch.
+
+Commits in ``release/x.y.z`` will be merged forward into ``develop`` periodically by the core developers.
+
+If in doubt about which branch to work from, ask on the #django-cms IRC channel on `freenode`_ or the
 `django-cms-developers`_ email list!
 
+
+.. _commit_policy:
+
+Commit policy
+=============
+
+.. versionadded:: 3.3
+
+Commit messages
+---------------
+
+Commit messages and their subject lines should be written in the past tense, not present tense, for example:
+
+    Updated contribution policies.
+
+    * Updated branch policy to clarify purpose of develop/release branches
+    * Added commit policy.
+    * Added changelog policy.
+
+Keep lines short, and within 72 characters as far as possible.
+
+
+Squashing commits
+-----------------
+
+In order to make our Git history more useful, and to make life easier for the core developers, please rebase and
+squash your commit history into a single commit representing a single coherent piece of work.
+
+For example, we don't really need or want a commit history, for what ought to be a single commit, that looks like
+(newest last)::
+
+    2dceb83 Updated contribution policies.
+    ffe5f2c Fixed spelling mistake in contribution policies.
+    29168da Fixed typo.
+    85d925c Updated commit policy based on feedback.
+
+The bottom three commits are just noise. They don't represent development of the code base. The four commits
+should be squashed into a single, meaningful, commit::
+
+    85d925c Updated commit policy based on feedback.
+
+
+How to squash commits
+^^^^^^^^^^^^^^^^^^^^^
+
+In this example above, you'd use ``git rebase -i HEAD~4`` (the ``4`` refers to the number of commits being squashed -
+adjust it as required).
+
+This will open a ``git-rebase-todo`` file (showing commits with the newest last)::
+
+    pick 2dceb83 Updated contribution policies.
+    pick ffe5f2c Fixed spelling mistake in contribution policies.
+    pick 29168da Fixed typo.
+    pick 85d925c Updated commit policy based on feedback.
+
+"Fixup" the last three commits, using ``f`` so that they are squashed into the first, and their commit messages
+discarded::
+
+    pick 2dceb83 Updated contribution policies.
+    f ffe5f2c Fixed spelling mistake in contribution policies.
+    f 29168da Fixed typo.
+    f 85d925c Updated commit policy based on feedback.
+
+Save - and this will leave you with a single commit containing all of the changes::
+
+    85d925c Updated commit policy based on feedback.
+
+Ask for help if you run into trouble!
+
+
+.. _changelog_policy:
+
+Changelog policy
+================
+
+.. versionadded:: 3.3
+
+**Every new feature, bugfix or other change of substance** must be represented in the `CHANGELOG
+<https://github.com/divio/django-cms/blob/develop/CHANGELOG.txt>`_. This includes documentation, but **doesn't** extend
+to things like reformatting code, tidying-up, correcting typos and so on.
+
+Each line in the changelog should begin with a verb in the past tense, for example::
+
+    * Added CMS_WIZARD_CONTENT_PLACEHOLDER setting
+    * Renamed the CMS_WIZARD_* settings to CMS_PAGE_WIZARD_*
+    * Deprecated the old-style wizard-related settings
+    * Improved handling of uninstalled apphooks
+    * Fixed an issue which could lead to an apphook without a slug
+    * Updated contribution policies documentation
+
+New lines should be added to the top of the list.
+
+
 .. _security@django-cms.org: mailto:security@django-cms.org
 .. _django-cms-developers: http://groups.google.com/group/django-cms-developers
 .. _freenode : http://freenode.net/

docs/how_to/contributing.rst

@@ -68,10 +68,7 @@ The basic workflow for a code contribution will typically run as follows:
 Target branches
 ===============
 
-The django CMS project will always have at least two active branches:
-
-* ``support/version.x`` which you should target if you're submitting a bug-fix for ``version.x``
-* ``develop`` for new features and bug-fixes for the next release
+See :ref:`branch_policy` for information about branch policy.
 
 
 *******************
@@ -223,6 +220,9 @@ Matching these criteria from the very beginning will help the core developers to
 to review your submission more quickly and efficiently and will increase the chances of making a
 successful pull request.
 
+Please see our :ref:`development_policies` for guidance on which branches to use, how to prepare pull requests and so
+on.
+
 Features
 --------
 

docs/spelling_wordlist

@@ -52,6 +52,7 @@ boilerplates
 cacheable
 callables
 changelist
+Changelog
 checkboxes
 clickable
 Clickjacking
@@ -85,6 +86,7 @@ fieldset
 filenames
 fillable
 Firefox
+Fixup
 formset
 Foulis
 framebuffer
@@ -161,6 +163,7 @@ prized
 Procida
 programmatically
 queryset
+rebase
 recurses
 refactor
 runserver