Plone 3.2 - Dec, 2008
=====================

Beginning with Plone 3.2, Plone will be available as a Python package and via
installers. It will no longer be distributed as a tarball of old-fashioned Zope
products. The change to standard Python packaging will improve dependency
handling and make future installations easier. But, it will require some
adjustments for those used to installing via a tarball of products. The 3.2
installation will also require some slight changes in the buildout
configuration file for those who have already been using buildout configuration
management in the 3.x series.

Plone's installers take care of all this for you, but if you aren't using one
of the installers you'll need to learn buildout -- a Python configuration
management tool we highly recommend -- or use the Python package installer,
easy_install, to install Plone. Both methods are discussed below.

Windows Updates
---------------
Users of past Windows installers should note: you should not try to simply
install on top of your old Windows installation. That might have worked in the
past, but it won't work with this upgrade. The move to a buildout-based
installer has changed the layout of the subdirectories inside the installation.
Do a new installation, get it working with all required products, then copy
your old Data.fs file over the matching file in the new installation.

Buildout
--------
All Plone's current installers use Buildout for configuration management. You
should too, unless you're very experienced with Python packages. Buildout is
the de facto standard for deploying Zope applications in a repeatable and easy
way.  The description of what will be installed is defined by a buildout
configuration file, buildout.cfg.

Buildout files for 3.2 look slightly different to those for 3.0 and 3.1 – they
don't need a custom plone installation step as buildout can now handle it
directly:

    [buildout]
    # parts: note that the plone part is no longer necessary.
    parts = 
        zope
        instance
    
    # find-links: only the new dist.plone.org URL is needed.
    find-links = 
        http://dist.plone.org/release/3.2
    
    # New: this will pick up version settings for all the components.
    # Modify the "3.2rc1" to match the version you're seeking.
    extends = http://dist.plone.org/release/3.2rc1/versions.cfg
    versions = versions
    
    # eggs: Plone is now specified in the egg section. All the
    # dependencies are automatically handled.
    eggs =
        Plone
    
    # zope part: Note the new fake-eggs settings. This is required
    # for Zope dependencies to be resolved during buildout.
    [zope]
    recipe = plone.recipe.zope2install
    url = http://www.zope.org/Products/Zope/2.10.6/Zope-2.10.6-final.tgz
    fake-zope-eggs = true
    additional-fake-eggs =
        ZConfig
        pytz
    
    # Everything else can usually be the same.
    [instance]
    recipe = plone.recipe.zope2instance
    zope2-location = ${zope:location}
    ...
    
If you have already modified your buildout.cfg file, for example to install new
add-ons, remember to copy what you added to the eggs= and zcml= lines into the
[instance] section. 

If you've installed "old style" products you'll need to copy the productdistros
section and add it to parts too.

Custom buildout
----------------
To convert your existing custom buildout to Plone 3 is very easy.  The above
example should be enough to make it clear what's needed, but in summary:

1. Remove the [plone] section and its entry from parts

2. Add the Plone egg to the eggs specification. Note that "Plone" is
   capitalized.

3. Copy the extends= and versions= directives from above into your buildout,
   updating the version number to the target release.

4. Modify the dist.plone.org line in find-links to match the version, as above.

5. Add the two "fake-eggs" specifications above to the zope part specification.

easy_install and virtualenv
---------------------------
If you wish to use the Python package installation tool easy_install, you may
install Plone into your Python environment by running:

    easy_install Plone

Note that you may need to use easy_install-2.4 or specify the precise path of
the Python 2.4.x that you're using with your Zope environment.

Installing Plone via easy_install alone, though, may be hazardous to your
system Python and your mental health, as various Python modules may require
different versions of components. We highly recommend that you use virtualenv
to create an isolated Python instance before proceeding.

Version Migration
=================

No matter which technique you use to ugrade your Plone version, you'll need to
use the portal_migrations tool in the Zope Management Interface to update your
object database. This step is unchanged from past installations.

 


Plone 3.1 - Apr, 2008
=====================

The following is a list of important things to note when installing or
upgrading to Plone 3.1:

* Unpacking the Plone archive with WinZip will not work: WinZip will truncate
  filenames without warning you. 7-Zip is a good open source alternative for
  Windows that you can use instead: http://www.7-zip.org

* Zope 2.10.4+ is now required. Older versions of Zope will not work. Zope
  2.11 and later may or may not work. Zope 3.x is not supported.

* The python ElementTree package is now required. This package can be
  downloaded from its home page at http://effbot.org/downloads/#elementtree .

* The python lxml package is now required to run all tests. It is
  not needed for normal Plone use. This package can be downloaded
  from its home page at http://codespeak.net/lxml/ .

* The Python OpenID packages are required if you want to enable OpenID support.
  They can be downloaded from the OpenID enabled site at
  http://www.openidenabled.com/resources/downloads/python-openid/
  Your python must also be compiled with SSL support.

* Plone 3.0 uses both Zope Products and python packages. The Zope Products
  are installed in the usual location: the Products directory of the Zope
  instance. Python package may be installed in the lib/python directory in the
  Zope instance, or anywhere on the standard python path.

* The GroupUserFolder user folder is no longer supported; instead Plone
  now requires the Pluggable Authentication System (PAS). It may not be
  possible to upgrade a site using GRUF with external user folders such as
  LDAPUserFolder. In those cases it is advised to create a new site and move
  the content over manually.


Important notes for users
-------------------------

Plone 3.1 adds new features to Plone 3, while maintaining full compatibility
with Plone 3.0. All products written for Plone 3.0 should work normally on
Plone 3.1 as well.

A complete list of changes can be found online at
http://plone.org/products/plone/releases/3.1 . The most important changes are:

* new portlets have been added: a rich text field portlet which can show
  arbitrary text as well as a portlet which will show items from a collection.

* Products and packages can now define dependencies, which will automatically
  be installed when necessary.

* The jQuery javascript library is now used throughout Plone and is available
  for use by add-on products. Of course KSS is still present as well.

* GenericSetup profiles can now be used to manage creation and removal
  of both content rules and portlets.

* Security sensitive forms accessible by users are now protected against
  Cross Site Request Forging-attacks.



Important notes for site and system administrators
--------------------------------------------------

For migration instructions please see the online Plone upgrade manual:
http://plone.org/upgrade

* Plone 3 now uses a new session authentication implementation based on the
  new plone.session package. This system uses a cryptographic hash against
  the userid of a successfully authenticated user to authenticate sessions.

  This form of session authentication only works for users defined in the
  user folder in the Plone site itself. Users defined in other user folders
  (such as the global admin user defined in the Zope root) will work, but
  use the authentication methods configured in their user folder. This
  means that they will be less secure than users defined in the Plone site.

* Member folders are no longer enabled by default.

* In order to use the automatic indexing of Word and PDF files you will
  need to install some external tools: indexing of MS Word files requires
  the wvware product to be installed. For PDF files either the pdftotext
  of xpdf suite is required.


Important notes for developers new to Plone 3
---------------------------------------------

The latest information on migrating products to Plone 3.0 can be found online
at http://plone.org/documentation/manual/upgrade-guide/version/2.5-3.0/products

* Searching for users and groups using the portal_membership and portal_groups
  tools has been deprecated. Please use the search features of PAS directly
  or use the PlonePAS pas_search browser view.

* There are new Reader, Editor and Contributor roles, roughly mapping to
  View/Access contents information/List folder contents, Modify portal content
  and Add portal content, respectively. They are to be used only as local
  roles, via the improved "sharing" tab. 
  
  If you have custom workflows, you may want to amend them to use these roles. 
  
  If you use custom add permissions for your content types, you may want to
  give them to the Contributor role by default.
  
* You are no longer expected to have a "Sharing" tab, implemented as an
  action with id 'local_roles', on your custom content types. This is now a 
  global action, in the 'object' category. If your type provides such an
  action, there will be two "Sharing" tabs. Also note that the sharing action
  is now called @@sharing, not folder_local_role_form.

* Portlets have been re-implemented using the Zope 3 component architecture.
  The base package, plone.portlets, is usable in plain Zope 3 and has been
  successfully used with Grok. See its README.txt for full details on the
  architecture (you are only likely to need this if you need to understand
  how portlets are wired into Plone's core - you need to know considerably
  less to understand how to use and make portlets, and there is a much
  improved UI for site administrators).
  
  The easiest way to re-use an existing template-based portlet is to use a
  Classic Portlet from the "Manage portlets" screen, although this will suffer
  some performance overhead. It is better to make a new-style portlet. These
  allow you to keep configuration data associated with a particular portlet
  assignment, using formlib, and gives you a well-defined place to put
  Python logic powering the portlet. See plone.app.portlets.portlets for
  plenty of examples, or http://svn.plone.org/svn/collective/collective.portlets.
  
  Note that the left_slots and right_slots properties are no longer used.
  The "manage portlets" screen will allow you to migrate existing properties
  in a particular folder (those at the root of the portal are migrated when
  Plone is upgraded). To manage portlet assignments, use the APIs described
  in plone.portlets.interfaces, or see plone.app.portlets.browser.editmanager.

* Skins: main_template now uses viewlet managers instead of metal macros
  -> Alexander Limi or Florian Schulze to fill in stuff here. Affected
  are at least header.pt, viewThreadsAtBottom and global_contentmenu

* It is no longer possible to define workflows using python code. Instead
  workflows have to be created via a GenericSetup profile.
  
* The new default workflow is simple_publication_workflow. If you have tests
  which can't handle this, you should fix them. However, to get a test fixture
  with the old plone_workflow as default, you can do:
  
    setupPloneSite(extension_profiles=['Products.CMFPlone:testfixture'])

  This sets up the CMFPlone test fixture extension profile, which ensures
  the default is plone_workflow.

* The long deprecated Products.CMFCore.CMFPermissions module has been
  removed. Code should now use its replacement Products.CMFCore.permissions

* You can use the contentmigration product to write migrations for your own
  products.  More information on this product can be found in the RichDocument
  tutorial: http://plone.org/documentation/tutorial/richdocument/migrations/

* If you have a custom content type that is derived from ATDocument but does
  not want the document-specific behavior that is provided on the IATDocument
  interface you should use the new ATDocumentBase base class instead.

* Customising z3 views using Customerize

* Products.CMFPlone.utils.BrowserView has been deprecated. If you were using
  this as a base class please use Products.Five.BrowserView instead. To
  get a correctly acquisition wrapped context use aq_inner(self.context).

Preferred but not obligatory (right now)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* QuickInstaller-based installation should use GenericSetup profiles instead 

* use events instead of `manage_` methods (which will probably disappear in
  Plone 4.0)

* Packaging technology:

  - Use python packages instead of Zope products. Creating python packages
    is very easy using the paster tool. See
    http://plone.org/documentation/how-to/use-paster/ for more information.

  - Use ploneit or ploneout to create development and/or production
    environments

  - Releasing packages as eggs and registering them with the Python Cheese
    Shop (http://cheeseshop.python.org/) makes it simple for people to
    install them and all required dependencies if they are using a system
    such as ploneout, ploneit or workingenv.

