#168: integrate iterate for checkin/checkout/staging

Contents

1. Motivation
2. Proposal
3. Risks
4. Progress log
5. Participants

Proposed by

Kapil Thangavelu

Seconded by

Alexander Limi

Proposal type

Architecture

Assigned to release

• Plone 3.0

Repository branch

plip-168-iterate

State

completed

Motivation

a common request for plone functionality, is the ability to edit content thats been workflowed and published, and subject those edits to workflow/review before publishing the content back. iterate adds that functionality to plone.

its designed to solve these use cases

Collaborative Document Editing Scenario
=======================================

Workgroup or person working on a document, the ability to checkout and lock a document
allows for a editing cycle, without concern of overwrites, and with an audit trail of
versions.

Publish/Modify/Review Cycles on a CMS
=====================================

A common theme in content management, is publishing a web document, and then needing
to revise it but not to change the published web content, till the modified document
has undergone a review cycle.

Proposal

the software is already built... see branch url

===============
Developer Guide
===============

a design walkthrough and configuration guide.

Components
----------

- Enabling Concurrent Development
Utilizes existing dav lock machinery, separate lock token namespace ( turns out to be
worthless since ).

- Versioning Repository
iterate utilizes cmfeditions for versioning.

- Iterations Tool
The tool itself is mostly a facade for easy access from z2 skin code to a checkin
checkout policy adapter, it does enforce api access w/ basic invariants, so adapter
implementations don't have to.


Checkin/Checkout Events
-----------------------

The easiest way to add additional behavior to the checkin / checkout process is to
configure an event subscriber to the Checkin and Checkout events. Examples of such
behavior are setting workflow and security for the checkout, or notifications on
checkin.

Configuration Checkin/Checkout Policy Adapters
----------------------------------------------

Policy Adapters control versioning behavior within the product, they
are currently responsible for implementing the checkin, checkout, and
cancelCheckout methods.

Terms::

Baseline
the original version of the content object, that the checkout was performed on.

Working Copy (WC)
a copy of the baseline, placed in a selectable container.

The default policy adapter its meant to be easily subclassed, see policy.py for details,
it does however have alot of responsibilities and maintains a series of invariants which
any replacement must also maintain, described below. if your business logic can be
encapsulated in an event subscriber it is much better to integrate it via that mechanism.

A policy's adapter adaptation context is a content object, by registered for by default
AT IBaseObject. Adapter configuration changes can be specified via zcml.

Checkin/Checkout Invariants
===========================

When a working copy is checked out a dav lock is taken out on the baseline, to prevent
mutation of the baseline. other forms of locking are available, but dav locks are the only common
infrastructure between different frameworks. this means currently only one checkout of
a given content object at a time.

A custom reference class ( see relation.py ) is used to store information about the checkout,
and recieve lifecycle events regarding the baseline, it is a reference between the
working copy to the baseline ( backref wc ).

Reference Adapters
------------------

are a plugin point for developers using/developing rich at reference applications
to have the flexiblity to implement support for custom reference classes, and change
backref policy.

Reference handling is a topic onto itself, see references.rst, if you dont use
backreferences, or custom reference classes, then the default configuration
which copies forward references to the working copy and merges any changes back,
should suffice.


Event Policy Adapter
---------------------

The primary place to put business logic relating to the
checkin/checkout process, is via an event policy adapter.

These adapters can also be utilized to change the content's workflow
(see Working Copy Workflow below).

What follows is an example of registering an event subscriber, to add
add the editor automatically to the Creators metadata on checkout.


An Event Policy Subscriber ( event.py )

.. from AccessControl import getSecurityManager

class MyPolicyAdapter:

def checkoutEvent( self, event ):
wc = event.working_copy
user_name = getSecurityManager().getUser().getUserName()
wc.setContributors( wc.Contributors() + (user_name,) )

And in $INSTANCE_HOME/etc/overrides.zcml or ProductName/overrides.zcml

..
<configure xmlns="http://namespaces.zope.org/zope">
<adapter
for="Products.Archetypes.interfaces.IBaseObject"
provides=".interfaces.IIterateEventPolicy"
factory=".event.MyPolicyAdapter"/>

</configure>

Working Copy Workflow
---------------------

WC workflow can be manipulated via an event policy adapter, as
demonstrated above, default behavior is that as a result of the copy
the workflow state of the working copy is reset to the default for the
content type. in plone 2.5 an object or container attribute market can
be utilized to signify a custom workflow for an instance or
containment structure. in plone 2.5, a custom workflow is utilized by
the default adapter to restrict availability of the checkout to only
the owner. The same behavior can be had in earlier versions by
installing cmfplaceful workflow.


Notes on Events Subscribers
---------------------------

aka Why Event Policy Adapters

In general raw publishing events, is a poor plugin point for
configuration, as subscribers are only additive, so base behavior is
always retained, apparently some work is being done to fix that for
Zope3.3.

To allow for plugin policy via events, iterate itself uses an event
subscriber which in turn delegates to a content adapter for event
handling, which in turn allows complete configuration for policy
via overrides.zcml


Permissions
-----------

Iterate utilizes two permissions, CheckinPermission which is an alias for
CMFEditions.SaveNewVersion and CheckoutPermission which is an alias for
CMFEditions.CheckoutToLocation.

Risks

iterate is pretty low risk, it builds on the work being done for cmfeditions integration and the locking plip, iterate merely adds features on top of these, its ui impact are a few object actions, and the codebase is small, and its internals use zope3 components and adapters for easy customization.

Progress log

see iterate-plip-168 review bundle

need to remove locking ui, and a nice addition would be to make cmfeditions and plone workflow ui respect locks.

Participants

Kapil Thangavelu