Merge branch 'develop' of ssh://github.com/ic-labs/django-icekit into…

… develop

.editorconfig

@@ -4,11 +4,20 @@ root = true
 
 [*]
 charset = utf-8
-end_of_line = lf
 indent_size = 4
-indent_style = space
 insert_final_newline = true
 trim_trailing_whitespace = true
 
+[*.{bat,iss}]
+end_of_line = crlf
+
 [*.{css,html,js,json}]
+indent_size = 2
 indent_style = tab
+
+[*.{py,sh}]
+indent_style = space
+
+[*.yml]
+indent_size = 2
+indent_style = space

.travis.yml

@@ -6,29 +6,24 @@ services:
   - docker
 
 install:
-  # Update apt sources. See: https://docs.docker.com/engine/installation/linux/ubuntulinux/
-  - sudo apt-key adv --keyserver hkp://p80.pool.sks-keyservers.net:80 --recv-keys 58118E89F3A912897C070ADBF76221572C52609D
-  - echo 'deb https://apt.dockerproject.org/repo ubuntu-trusty main' | sudo tee /etc/apt/sources.list.d/docker.list
-  - sudo apt-get update
-
-  # Docker Engine 1.9.x for build cache support. See: https://github.com/docker/docker/issues/20380#issuecomment-212388961
+  # Use Docker Engine 1.9.x for build cache support. See: https://github.com/docker/docker/issues/20380#issuecomment-212388961
   - sudo apt-get -o Dpkg::Options::="--force-confnew" -q -y --force-yes install docker-engine=1.9.1-0~trusty
 
-  # Docker Compose. See: https://github.com/docker/compose/releases
-  - curl -L https://github.com/docker/compose/releases/download/1.7.0/docker-compose-`uname -s`-`uname -m` | sudo tee /usr/local/bin/docker-compose > /dev/null
-  - sudo chmod +x /usr/local/bin/docker-compose
-
 before_script:
+  - docker --version
+  - docker-compose --version
+  - docker-compose -f docker-compose.travis.yml config
   - docker login -e="$DOCKER_EMAIL" -u="$DOCKER_USERNAME" -p="$DOCKER_PASSWORD"
-  - docker pull "interaction/icekit:${TAG}" || true
-  - docker build -t "interaction/icekit:${TAG}" .
+  - docker pull "interaction/icekit:$TAG" || true
+  - docker build --pull -t "interaction/icekit:$TAG" .
 
 script:
   - docker-compose -f docker-compose.travis.yml run --rm django
 
 after_success:
-  - docker push "interaction/icekit:${TAG}"
+  - docker push "interaction/icekit:$TAG"
 
 env:
   global:
-    - TAG=$(echo ${TRAVIS_BRANCH} | sed 's/[^0-9A-Za-z]/_/g')
+    # Use `pull-N`, Git tag, or Git branch as Docker image tag.
+    - TAG=$([[ "$TRAVIS_PULL_REQUEST" != "false" ]] && echo "pull-$TRAVIS_PULL_REQUEST" || echo ${TRAVIS_TAG:-$TRAVIS_BRANCH} | sed 's/[^.0-9A-Za-z]/-/g')

README.md

@@ -1,6 +1,7 @@
 [![Build Status](https://img.shields.io/travis/ic-labs/django-icekit.svg)](https://travis-ci.org/ic-labs/django-icekit)
 [![Coverage Status](https://img.shields.io/coveralls/ic-labs/django-icekit.svg)](https://coveralls.io/github/ic-labs/django-icekit)
 [![Documentation](https://readthedocs.org/projects/icekit/badge/)](https://icekit.readthedocs.io/)
+[![Requirements Status](https://img.shields.io/requires/github/ic-labs/django-icekit.svg)](https://requires.io/github/ic-labs/django-icekit/requirements/)
 [![Version](https://img.shields.io/pypi/v/django-icekit.svg)](https://pypi.python.org/pypi/django-icekit)
 
 [![Deploy to Docker Cloud](https://files.cloud.docker.com/images/deploy-to-dockercloud.svg)](https://cloud.docker.com/stack/deploy/)
@@ -27,10 +28,10 @@ If you're not ready for Docker, see [Manual Setup](docs/intro/manual-setup.md).
 
 ## 1. Create a new project
 
-    $ bash <(curl -Ls https://raw.githubusercontent.com/ic-labs/django-icekit/master/icekit/bin/startproject.sh) <project_name>
+    $ bash <(curl -Ls https://raw.githubusercontent.com/ic-labs/django-icekit/master/icekit/bin/startproject.sh) {project_name}
 
 This will create a new project from the ICEkit project template, in a directory
-named <project_name> in the current working directory.
+named `{project_name}` in the current working directory.
 
 NOTE: Windows users should run this command in Git Bash, which comes with
 [Git for Windows](https://git-for-windows.github.io/).
@@ -39,7 +40,7 @@ NOTE: Windows users should run this command in Git Bash, which comes with
 
 Build a Docker image:
 
-    $ cd <project_name>
+    $ cd {project_name}
     $ docker-compose build --pull
 
 Run a `django` container and all of its dependancies:

docs/changelog.md

@@ -1,6 +1,26 @@
 # Changelog
 
-## Next release
+## In development
+
+  * Fix bug where the content items and placeholders associated with a
+    fluent content model (other than a page) were not included in the
+    published copy.
+
+  * Provide `icekit.publishing.models.PublishableFluentContents` and
+    `icekit.publishing.admin.PublishableFluentContentsAdmin` as base
+    classes for fluent content models and admins, to help keep things
+    DRY.
+
+### Breaking changes
+
+  * Import model mixins `FluentFieldsMixin`, `LayoutFieldMixin`, and
+    `ReadabilityMixin` from `icekit.mixins` module instead of
+    `icekit.abstract_models`.
+
+  * Import admin mixin `FluentLayoutsMixin` from `icekit.admin_mixins`
+    module instead of `icekit.admin`.
+
+## 0.14.1 (26 September 2016)
 
   * ICEkit gets a facelift. Content editing now looks cleaner and easier to
     scan. Reordering items is animated, meaning it's easier to keep track of
@@ -12,8 +32,14 @@
     is useful to users who can't see them, though the `alt=` attribute is still
     always included in HTML.
 
-  * Fix a bug where looking for help_text in a placeholder slot that had no
-    manual configuration raised a 500, resulting in no layout data found
+  * Fix a bug where looking for `help_text` in a placeholder slot that had no
+    manual configuration raised a 500, resulting in no layout data found.
+
+  * Fix fatal error (typo) in `startproject.sh` script.
+
+  * Update `.editorconfig`, and add to project template.
+
+  * Tag Docker images during build on Travis CI for release versions.
 
 
 ## 0.14 (20 September 2016)

docs/contributing/contributing.md

@@ -53,6 +53,12 @@ port or a dynamic port:
 Read [Manual Setup](../intro/manual-setup.md) for more info on running an
 ICEkit project without Docker.
 
+# Installing the ICEkit dev version on an existing project
+
+    $ docker-compose exec django entrypoint.sh
+    $ pip install -e git+https://github.com/ic-labs/django-icekit.git#egg=django-icekit
+
+
 # Git branching
 
 We are using the [Gitflow] branching model. Basically:

docs/contributing/testing.md

@@ -0,0 +1,39 @@
+# Testing
+
+ICEkit uses a custom script `runtests.sh` to run tests, which configures the
+test database and restores from `test_initial_data.sql` if available,
+ to speed up migrations.
+
+## Recipes
+
+### To run icekit tests
+
+    runtests.sh path/to/icekit/
+
+### To run specific tests
+
+    runtests.sh foo.bar:Baz.test_foo
+
+### To discover tests in the current folder and run without migrations:
+
+    runtests.sh -n .
+
+### To create migrations for a test model
+
+    BASE_SETTINGS_MODULE=icekit.tests.settings manage.py makemigrations
+
+### To get an interactive shell to inspect the test database
+
+    BASE_SETTINGS_MODULE=icekit.tests.settings manage.py shell_plus
+
+### To speed up test running
+
+    QUICK=1 runtests.sh ...
+
+This reuses the test databases, and skips collectstatic and compress steps.
+
+To achieve permanent speedip, create a data dump called `test_initial_data.sql`
+with migrations applied. It will be restored to the test database in
+`runtests.sh`, bypassing all migrations.
+
+

docs/howto/commands.md

@@ -58,17 +58,17 @@ Display a list of other frequently used shell commands:
 
 ## Uninstalling an ICEkit project
 
-Delete all containers with a name matching `<project_name>`:
+Delete all containers with a name matching `{project_name}`:
 
-    $ docker rm $(docker ps -a -f "name=<project_name>" -q)
+    $ docker rm $(docker ps -a -f "name={project_name}" -q)
 
 To delete the associated images, run:
 
     $ docker images #list all images
 
 and for each image you want to delete:
 
-    $ docker rmi <image id>
+    $ docker rmi {image id}
 
 If you are running other ICEkit projects, then you only need to delete the
 image that starts with `[project_name]` - the other images will be used by

docs/howto/page-types.md

@@ -83,7 +83,7 @@ Here's a rough guide:
 | Static               | Yes                     | No          | `FluentContentsPage`                                      | `FluentContentsPageAdmin`                      |
 | Static               | Yes                     | Yes         | `PublishableFluentContentsPage` (use `PlaceholderField`s) | `(FluentContentsPageAdmin, PublishingAdmin)`   |
 | Dynamic              | No                      | No          | `FluentFieldsMixin`                                       | `FluentLayoutsMixin`                           |
-| Dynamic              | No                      | Yes         | `(FluentFieldsMixin, PublishingModel)`                    | `(FluentLayoutsMixin, PublishingAdmin)`        |
+| Dynamic              | No                      | Yes         | `PublishableFluentContents`                               | `PublishableFluentContentsAdmin`               |
 | Dynamic              | Yes                     | No          | `AbstractUnpublishableLayoutPage`                         | `UnpublishableLayoutPageAdmin`                 |
 | Dynamic              | Yes                     | Yes         | `AbstractLayoutPage`                                      | `LayoutPageAdmin`                              |
 

docs/howto/plugins.md

@@ -74,14 +74,14 @@ with two mixin classes:
 
     # models.py
 
-    from icekit.abstract_models import FluentFieldsMixin
+    from icekit.mixins import FluentFieldsMixin
 
     class MyModel(FluentFieldsMixin, MyModelBase):
         ...
 
     # admin.py
 
-    from icekit.admin import FluentLayoutsMixin
+    from icekit.admin_mixins import FluentLayoutsMixin
 
     class MyModelAdmin(FluentLayoutsMixin, MyModelAdminBase):
         ...

docs/index.md

@@ -1,4 +1,5 @@
-<!-- Comments are items which are to come -->
+[//]: # (Comments are items which are to come)
+
 # First steps
 
 Are you new to ICEkit? Start here.
@@ -74,7 +75,8 @@ ICEkit is open and free to use. However if you have a query or business need
 that doesn't belong in the public community, please get in touch with the ICEkit
 team at [the Interaction Consortium]: [labs@interaction.net.au](mailto:labs@interaction.net.au).
 
-<!--internal links -->
+[//]: # (internal links)
+
 [ICEkit features]: intro/features.md
 [Architectural overview]: intro/architecture.md
 [Quick install guide]: intro/install.md
@@ -94,7 +96,9 @@ team at [the Interaction Consortium]: [labs@interaction.net.au](mailto:labs@inte
 [Standards and collaboration]: contributing/contributing.md
 [Code of Conduct]: contributing/conduct.md
 [Roadmap]: contributing/roadmap.md
-<!-- external links -->
+
+[//]: # (external links)
+
 [icekit-events]: https://github.com/ic-labs/icekit-events
 [icekit-press-releases]: https://github.com/ic-labs/icekit-press-releases
 [issues]: https://github.com/ic-labs/django-icekit/issues

docs/intro/architecture.md

@@ -89,7 +89,7 @@ See the [Publishing] docs for an overview.
 ICEkit comes with an admin dashboard that allows you to prioritise major
 content types.
 
-<!-- ## Response Pages -->
+[//]: # (Response Pages)
 
 [django-fluent-contents]: https://github.com/edoburu/django-fluent-contents
 [django-fluent-pages]: https://github.com/edoburu/django-fluent-pages

docs/intro/install.md

@@ -14,10 +14,10 @@ If you're not ready for Docker, see [Manual Setup](manual-setup.md).
 
 ## 1. Create a new project
 
-    $ bash <(curl -Ls https://raw.githubusercontent.com/ic-labs/django-icekit/master/icekit/bin/startproject.sh) <project_name>
+    $ bash <(curl -Ls https://raw.githubusercontent.com/ic-labs/django-icekit/master/icekit/bin/startproject.sh) {project_name}
 
 This will create a new project from the ICEkit project template, in a directory
-named <project_name> in the current working directory.
+named `{project_name}` in the current working directory.
 
 NOTE: Windows users should run this command in Git Bash, which comes with
 [Git for Windows](https://git-for-windows.github.io/).
@@ -26,7 +26,7 @@ NOTE: Windows users should run this command in Git Bash, which comes with
 
 Build a Docker image:
 
-    $ cd <project_name>
+    $ cd {project_name}
     $ docker-compose build --pull
 
 Run a `django` container and all of its dependancies:

docs/intro/manual-setup.md

@@ -34,6 +34,15 @@ zlib needs to be installed from the `dupes` repository and force linked:
 You need to configure Elasticsearch, PostgreSQL and Redis to start
 automatically, or start them manually before you start the project.
 
+### Installing after an OS X upgrade
+
+If you experience errors running `./go.sh` after an upgrade to OS X try
+installing Xcode command-line tools:
+
+    xcode-select --install
+
+You may also need to re-install system packages.
+
 ## Run without Docker
 
 Change to the ICEkit project template (or an ICEkit project) directory:

docs/topics/publishing.md

@@ -41,6 +41,11 @@ To make a `FluentContentsPage` model publishable:
 * subclass your model from `icekit.publishing.models.PublishableFluentContentsPage`
 * subclass your model's admin from `FluentContentsPageAdmin` and `icekit.publishing.admin.PublishingAdmin`
 
+To make a fluent contents model (see [ContentsPlugins]) publishable:
+
+* subclass your model from `icekit.publishing.models.PublishableFluentContents`
+* subclass your model's admin from `icekit.publishing.admin.PublishableFluentContentsAdmin`
+
 #### Note: Validating slug uniqueness
 
 In publishable models, both the draft and published slugs will be identical,
@@ -118,6 +123,8 @@ published items for everyone else:
   happens to be a draft or published copy. This is basically equivalent to
   `get_visible() is not None`.
 
+#### Draft Content Protection
+
 If you forget to explicitly look up the visible version of publishable items,
 you will get the draft version instead and could risk displaying draft
 content to the public. To avoid this, the publishing implementation includes
@@ -126,6 +133,12 @@ a message like *"Illegal attempt to access 'title' on a DRAFT publishable
 item..."*. If you see that, check that you are obtaining the correct visible
 or published version of items.
 
+If you are sure you want to access draft attributes within a published context,
+you can use `get_draft_payload()` on the draft item, or add the attribute to
+`PUBLISHING_PERMITTED_ATTRS` on the model. `pk` is accessible by default, but
+most other attributes (particularly reverse relations) will need to be added
+to `PUBLISHING_PERMITTED_ATTRS` individually.
+
 For some situations you might need to get just the published or draft copies
 of items, such as for the search indexes we only ever want published copies
 to be indexed regardless of the privileges of the user/process that triggers
@@ -163,6 +176,21 @@ item you are working with happens to be a draft or published copy, use the
 `has_been_published` property. This returns `True` if the item is itself
 published, or is a draft that has a published copy.
 
+#### Relating/retrieving items that are related to draft versions
+
+Since only draft versions are shown in the admin, and a published version isn't
+constantly available, it usually makes sense to to define relations to the draft
+version of an object.
+
+That means that a published version won't have incoming relations, and accessing
+reverse relations on the draft version will set off the booby trap, unless the
+`related_name` is added to `PUBLISHING_PERMITTED_ATTRS`.
+
+A pattern like this is normally safest (`pk` is a permitted attribute):
+
+    RelatedModel.objects.filter(fk_id=self.get_draft().pk)
+
+
 ### Data model
 
 The general gist is that every item in Django's CMS admin is created a
@@ -225,3 +253,5 @@ rendering related content for the public and for site admins:
 There has been an issue discovered where `ManyToMany` fields referring both
 ways on models have the many to many data cloned for published and
 unpublished objects. This is currently being worked on.
+
+[ContentsPlugins]: ../howto/plugins.md