.. -*- coding: utf-8 -*- StagingAddOn - staging and versioning in Plone ============================================== StagingAddOn is a simple staging and versioning product. It allows: - to have a published version of an item, while working on a new version (located in the same folder). When this new version is published, the old one can be automatically archived or expired; - to list versions of an item; - to compare two versions of an item, if CMFDiffTool is installed. This products aims to be an easy-to-install and easy-to-use solution. .. contents:: Usage ----- Suppose that we have installed StagingAddOn and that our portal has a folder at ``/folder`` and a document at ``/folder/document`` whose title is "Document v1". 1. "Document v1" is published. 2. We decide to create a new version of this item. But we also want to keep a published, accessible version, during the edition of this new version. To do that, we select the "create new version" workflow action. This duplicates "Document v1" in the current folder (``/folder/document-new-version``) and redirects the user to this new item. 3. This new item is in the initial state of the workflow ("visible", for the default Plone workflow). We can modify it, rename it as "Document v2" for example. We can also submit if we have the permission to. 4. When this new item is published, the following happens: - the original document ("Document v1") is renamed as ``/folder/document-old-version-replaced-15042006-161234``; - the new version is renamed as ``/folder/document`` to replace the original document. - the original document is automatically expired (if the configuration says so); - a workflow transition ("archive" for example) is automatically triggered on the original document (if the configuration says so). There are now two items: - ``/folder/document``: "Document v2"; - ``/folder/document-old-version-replaced-15042006-161234``: "Document v1". Note that any reference to the previously published version now points to the new version. It includes "related items", LinguaPlone translations, text links if Kupu's "resolve UID" feature is enabled, etc. For further informations, see ``tests/testUsage.py``: the included tests explains (in Python and in English) what StagingAddOn really does, and how to interact with its API. Workflow requirement -------------------- The current implementation does customize your workflows when you configure it, because staging is about workflow, after all... However, the core features of StagingAddOn can be used and/or extended without using workflows. This would require user interfaces and some glue code, but this is possible. This will probably not be implemented. Next major version of StagingAddOn will use Zope events and will therefore less interfer with the installed workflows anymore (it will merely add a transition, without adding "before scripts" to existing transitions). See `Future features`_ section below. Other products (a.k.a. "the big warning section") ------------------------------------------------- Staging and versioning are very important features that Plone is aiming to provide out of the box in the upcoming 3.0 release. Until it is released, you probably want to use the right product. StagingAddOn may not be the right tool to use. I strongly suggest to read a bit more about other products which might better fit your own needs. Note that I have tried to be objective but, still, these are not the definitive description of the products. These are (only) my opinion, which I drew from tests I have done a few months ago (end of 2005, actually; note that these descriptions are still accurate in June 2007). You *really* want to try them out to decide which product should be yours. CMFEditions_ as of this writing, this is the preferred way of having multiple versions of a single item in CMF (and thus Plone). Unfortunately, it does not provide any staging feature: it is not possible to work on a version of an item while having another version published. I tend to dislike CMFEditions because of its UI. You do not really "create" a new version: you rather mark the current item as a new version. I am not sure this is all that easy to understand for end-users. .. _CMFEditions: http://plone.org/products/cmfeditions Iterate_ Kapil Thangavelu "put together a product for simple staging and collaborative document editing [...] it builds on top of cmfeditions to offer explicit checkin and checkout functionality with locking" (from his e-mail on plone-developers mailing list). It is a great product on top of CMFEditions. If you like CMFEditions, you might want to give 'iterate' a try. It does not "invade" your workflow (contrary to StagingAddOn) and you should be able to implement StagingAddOn features (e.g. automatic replacement of the current version when the new version is published) without too much hassle. .. _Iterate: http://plone.org/products/iterate EnSimpleStaging_ as of this writing, this product provides advanced staging features, with separate workspaces: a staging area, where changes are done, and a "public" area where the visitors can actually view items. This might be overkill and/or not suitable for your own need (specifically if your use case is an intranet portal). Also note that the configuration of the product can be uneasy: you should take a look at the "README" file and the tutorial on plone.org. In short: this is probably a great product which is worth using it, if it suits your use case and if you succeed in configuring it. .. _EnSimpleStaging: http://plone.org/products/ensimplestaging There may be other products, but either they do not work with Plone 2.1 (or later) or I am not aware of them. Note that "CMFEditions" and "iterate" will be part of the upcoming 3.0 release of Plone. But still, if you use Plone 2, these products might not yet be integrated enough with Plone, so this is not necessarily the way to go. Anyway, StagingAddOn will work with Plone 3.0, so you can be sure that the migration to Plone 3.0 is guaranteed and will be as smooth as possible. Dependencies ------------ StagingAddOn has the following dependencies: - Zope 2.8.x or Zope 2.9.x - Plone 2.1.x or Plone 2.5.x Note that this product might work on a plain CMF portal with some slight changes. This has not been tested, though. Installation ------------ 1. Read the `right documentation`_ if you have never installed any product. 2. Install the product in the file system. 3. Install the product in your Plone portal, via the Plone control panel. 4. Click on the "Configuration of StagingAddOn" configlet on the left column of the Plone control panel. 5. Add a new "StagingAddOn configuration" item and fill the edit forms. .. _right documentation: http://plone.org/documentation/tutorial/third-party-products/installing Important notes --------------- If you have added an "after script" (scripts which are called after the transition) to the 'publish' transition of your workflow, the current installation mechanism will fail. Basically, it will refuse to replace your script by its own script. Which is nice, isn't it? In that case, taking a look at the ``install()`` method in ``content/configuration.py`` should help. In the same way, uninstallation of StagingAddOn may fail. This is a somewhat known problem, but I am not very willing to fix that, because of the number of cases where we simply cannot uninstall things without risking to break workflow customizations. In these cases, reading the ``unInstall()`` method in 'content/configuration.py' should give you a good insight of how you can manually uninstall StagingAddOn. Hopefully, StagingAddOn 2.0 will be much less invasive. See `Future features`_ below. Other informations ------------------ Other informations (including a complete how-to in Python) are located in the ``doc/`` folder. Future features --------------- - specific LinguaPlone support: for now, LinguaPlone items are seen as standard items. This may not be the best policy: we may want to copy-paste all translations, for example. But maybe not. Nobody have asked for such specific features yet, so we did not have taken time to think about it; - rollback: for now, there are no rollback features. I am not sure that there will be, though. There again: no use-case, hence no specification, hence no implementation. The 2.0 version of StagingAddOn will use Zope 2.9 and CMF 2 features. The event system will allow us to be less invasive toward the workflow. However, the use of these features means that SAO 2.0 will not be compatible with versions prior to Plone 3 anymore. Credits ------- The development of this product has been initially (up to version 0.9) sponsored by Materis. Thanks to them! It has then been developed by `Pilot Systems`_. .. _Pilot Systems: http://www.pilotsystems.net The following people have contributed to this product: - Damien Baty (damien AT pilotsystems DOT net - Pilot Systems): original author, tests, documentation, maintenance; - Sylvain Viollon (sylvain AT pilotsystems DOT net - Pilot Systems): various bug fixes and insightful ideas; - Souheil Chelfouh (souheil AT pilotsytems DOT net - Pilot Systems) and Gaël Pasgrimaud: insightful ideas; - Sune B. Woeller (sune AT woeller DOT dk): bug reports and comments about references-related issues in Archetypes and StagingAddOn; - Sven Deichmann: translation in German; - Piotr Furman (piotr DOT furman AT webservice DOT pl - WebService.pl): translation in Polish; - Luca Fabbri (luca DOT fabbri AT redturtle DOT net - RedTurtle): translation in Italian; - Luis Flavio Rocha (lflrocha AT gmail DOT com) : translation in Brazilian Portuguese. Bug report and patches ---------------------- Please report bugs at http://plone.org/products/stagingaddon/issues. Patches, ideas and tests are much welcome. However, please do not add new features without prior discussion with the maintainer. StagingAddOn aims at being and remaining simple, before all else. License ------- See ``LICENSE.txt``.