1. Ploneアップグレードガイド
    1. 1. 導入
      1. バージョン番号に関する決まりごと
    2. 2. 準備
      1. 情報収集
      2. Ploneサイトのバックアップの取得
      3. 移行リハーサル用のテスト環境の作成
    3. 3. 全般的な手順
    4. 4. アドオンプロダクトのアップグレード
    5. 5. トラブルシューティング
      1. ログファイルのチェック
      2. カスタマイズをしない状態でのテスト
      3. プロダクトを何も追加しない状態でのテスト
      4. 新規Ploneインスタンスでのテスト
      5. 再現可能な問題点の確認
      6. メーリングリストへの問い合わせ
      7. バグ報告
    6. 6. バージョン固有の移行手順とヒント
      1. 6.1. Plone 1.0 から 2.0 へのアップグレード
        1. 2.0への移行にともなう副作用
        2. テンプレート/CSS の変更点
        3. base_properties
        4. 用語集
        5. Windows Installer
      2. 6.2. Plone 2.0 から 2.1 へのアップグレード
        1. 移行およびバージョン番号についての注意
        2. 移行について
        3. 移行作業
        4. ありがちな問題
        5. Additional notes
        6. Tip: How to re-customize your templates
        7. Postscript
      3. 6.3. Plone 2.1 から 2.5 へのアップグレード
      4. 6.4. Plone 2.5 から 3.0 へのアップグレード
        1. 6.4.1. アドオンプロダクトを Plone 3.0 に対応させる方法
          1. 6.4.1.1. プロダクトを Plone 3.0 に対応させるための一般的な開発手法とヒント
          2. ヒント
          3. その他の推奨事項
          4. 6.4.1.2. CMFCore.permissions のインポート方式の変更
          5. 6.4.1.3. Transactionモジュールが、Archetypesに暗黙的に組み込まれることがなくなった
          6. 6.4.1.4. get_transaction モジュールの名前の変更
          7. 6.4.1.5. ContentFactoryMetadata? の廃止
          8. 6.4.1.6. ワークフローを、GenericSetupプロファイルを用いるように変更する
          9. 6.4.1.7. Membershipツールによるユーザやグループの検索が非推奨に
          10. 6.4.1.8. ポートレットの構造の変更
          11. 6.4.1.9. main_template now uses Zope 3 viewlets
          12. 6.4.1.10. Plone 3 does not create member folders by default
          13. 6.4.1.11. Plone Tableless theme no longer exists
          14. 6.4.1.12. Document Actions now use Zope 3 viewlets
          15. 6.4.1.13. Products installing workflows may need to add permissions
          16. 6.4.1.14. Indexes declared in Archetypes schemata need to be moved to …
          17. 6.4.1.15. The "Sharing" tab is now a global action
          18. 6.4.1.16. Multi page schemas

Ploneアップグレードガイド

新バージョンのPloneにアップグレード（移行）するための手順とヒントをまとめました。

1. 導入

Ploneのアップグレードって、いったいどういうこと？

ここでいう「移行 (migration)」とは、Ploneサイトのコンポーネントの一部を古いバージョンから新しいバージョンに変える作業のことです。ほとんどの人にとって、これはPloneの新リリースへのアップグレードを意味することになるでしょう。たとえば、Ploneの2.1.3から2.5へ「移行」するといった意味合いになります。

新機能を追加する際にPloneの内部構造が変更される可能性もあるので、移行作業は欠かせません。新しいバージョンに移行すると、既存のPloneインスタンスに保存されているコンテンツがうまく動かなくなる可能性があります。Ploneには、既存のコンテンツを新しい構造に対応させるためのツールが組み込まれています。

この文書で説明するのは、異なるバージョンのPloneにアップグレードするための手順です。

実際に移行作業を行う前に、この文書を最後まで読み、Ploneサイトを移行することによってどんな影響が出る可能性があるのかを理解しておきましょう。特に「ありがちな問題」については熟読してください。

このガイドは、最近のすべてのバージョンのPloneを対象としています。また、もうサポートが打ち切られている古いバージョンについての情報も、参考として残してあります。

バージョン番号に関する決まりごと

Plone 2.1までは、メジャーリリースのたびに 0.1 ずつバージョンを上げていくという方針でした。標準のフレームワークの方針と似ています。しかし、この方式だと、バージョンアップの手間が実際より軽く見られてしまいがちという問題がありました。というわけで、バージョン番号のつけ方を変更することにしました。

Starting with the 2.5 release, the Plone Team aims to release a new version roughly every 6-9 months, so we have moved to a policy that increases the version number by 0.5 on every significant release. This means that when we say a "major release", we are referring to a x.0 or x.5 release, whereas a minor release has the version numbering 2.5.x or 3.0.x.

In addition to this general procedure there are excellent version-specific migration guides. These guides contain more specific instructions and valuable information that has been collected from real-life migration cases.

2. 準備

Ploneの移行作業の前にしておくべきこと

情報収集

  1. Read the "What's new in..." for your relevant plone version, and read the release notes. You'll find these in the CMFPlone directory of the distribution of the new version of Plone.
  2. Check for dependencies
    • Read the release notes for the Plone release you are upgrading to, in particular:
      • What version of Python is required?
      • What version of Zope is required?
      • Do you need any new python libraries?
    • Make sure all the add-on products you are using have updated to support the version of Plone you are upgrading to.
    • Start with the third-party products that are in use on your site. Verify that they have been updated or verified to work on the new version, and get them upgraded in your existing instance before you start the Plone/Zope/Python upgrade if possible.
    • If Zope depends on a newer version of Python, install the new version of Python first.
    • If the newer version of Plone depends on a newer version of Zope, you will need to install that before proceeding with the Plone upgrade.
      • NOTE: Zope has it's own migration guidelines, which you will find in the release notes of the version you are migrating to. If Plone is being upgraded at the same time as a Zope version, Plone will usually handle the Zope upgrade with its own migration script.
    • Read the following files in the CMFPlone directory of the distribution of the new version of Plone you want to update to:
      • README.txt
      • INSTALL.txt
      • UPGRADE.txt (although this usually contains only the general procedure outlined above)
    • These files are important because they may contain important last minute information and might be more specific than the relevant sections of this reference manual.

Ploneサイトのバックアップの取得

It's very important to back up your Plone site. You will find an excellent how-to on backing up your Plone site here.

移行リハーサル用のテスト環境の作成

Never work directly on your live site until you know that the upgrade was successful. Instead, create a test environment to rehearse the upgrade. Copy your instance into a new environment and upgrade the copy. This is a good way of working out your third party products and dependencies in preparation for the final upgrade of the live site!

3. 全般的な手順

A quick overview of the steps to migrate your site. This is how you do most of the migrations, and is generally all that is requred for upgrades between minor versions of Plone.

When upgrading to a newer release of Plone, it is important to run the migration procedure, since internal structures in Plone might have changed since the last version. This is the general procedure for upgrading.

Before you start upgrading anything, make sure you have a backup.

The basic manual procedure is detailed below. If you are using the installers, you can skip the part about moving away directories and replacing them with the new ones (step 3-4) - it should be handled by the installer for you.

  1. Back up your entire Plone directory
  2. Shut down your Plone server instance
  3. Remove the Product directories you want to replace (ie. the ones in the package you downloaded)
  4. Put in the new Product directories
  5. Start Plone again - your site may be inaccessible until we have performed the next steps - don't panic :)
  6. Go to http://yoursite/manage (aka. the ZMI) and click portal_migrations
  7. Click the Migrate tab - it will state something like: 
           Instance version: 2.1.2
           File system version: 2.1.3
  1. This means that you have to run the upgrade procedure to be updated to 2.1.3.
  2. Click the Upgrade button.

If you want to make sure that the migration runs, you can check the Dry Run option - this will do the exact same steps as a normal migration might do, but not write anything to the database.

  1. The site will now be updated, this may take a while, depending on which versions you upgrade from/to. For example, the upgrade from Plone 2.0 to Plone 2.1 involves conversion and re-cataloging of all content in your site, so if you have a big site, this may take a while. Be patient.

For those of you who wonder why we don't do this automatically, the reason is that we don't want to change your data without you knowing it, and you should have the opportunity to back up the data before doing this, etc.

For advanced/enterprise users: It is normally possible to upgrade in-place (at least between minor versions) without any site downtime if you run ZEO and multiple load-balanced instances. See the ZEO documentation for more information if you need this.

4. アドオンプロダクトのアップグレード

The steps to take to migrate your third party products

  1. Shut down your Plone server instance
  2. Navigate to your Plone instance product directory
  3. Remove the directories of the products you want/ need to replace
  4. Copy the new product directories across, and check that the permissions on each product directory are correct
  5. Start Plone again - your site may be inaccessible until we have performed the next step - don't panic :)
  6. Navigate to the quickinstaller in the ZMI, and reinstall or upgrade products if you can (products that support both your current and new version of Plone). Perform product-specific upgrade procedures (if any). You will find these in the docs of each product

5. トラブルシューティング

What to do when a problem occurs during a Plone migration.

When a problem occurs during the migration we recommend that you take the following steps.

ログファイルのチェック

When a site error occurs, or Zope fails to start, there's probably an informative error message in Zope's log files. Locate these log files and inspect event.log. Ignore irrelevant warnings and search for words such as error, exception and traceback (case-insensitive).

When Zope doesn't start and there's no useful information in the log file, you can start Zope interactively and watch for error messages in the output: 

    zopectl fg

You may be able to find more information on the error messages in:

カスタマイズをしない状態でのテスト

When you have customized page templates or Python scripts, your changes may interfere with changes in the new version of Plone. It's important to rule out this possibility, since your customizations are unique to your site and no one on the planet will be able to help you solve it.

Temporarily remove your customizations, for example by removing your layers from portal_skins, or by removing files from these layers on the file system. If the problem disappears, you'll need to doublecheck your customizations. It's usually best to copy the original files of the new version of Plone to your skin, and re-customize those.

プロダクトを何も追加しない状態でのテスト

Bugs or compatibility problems in products that you have installed may cause problems in Plone. Go to Site Setup > Add/Remove Products and remove (uninstall) all product that are not distributed with Plone. Remove the uninstalled products from the Products directory of your Zope instance.

If the problem disappears, you'll need to doublecheck the offending product:

  • Does it support the new version of Plone, Zope and Python? Check the product's README.txt or other informational files or pages.
  • Does the product require any additional migration procedures? Check the product's INSTALL.txt, UPGRADE.txt or other informational files or pages.
  • Does the product install properly? Re-install it and check the install log.

新規Ploneインスタンスでのテスト

Create a new Plone site with your new version of Plone. You don't need a new Zope instance, since you can add another Plone site in the root of Zope. If the problem does not occur in a fresh site, the cause of your problem is most likely a customization, an installed product or content that was not migrated properly.

再現可能な問題点の確認

Before you go out and ask for help, you should be able to describe your problem in such a way that others can reproduce it in their environment.

Reduce the problem to the smallest possible domain. Eliminate products and customizations that are not part of the problem. This makes it easier for others to reproduce the problem and it increases your chances of meeting others with the same problem or even a solution. The more complex your story is, the more likely that it is unique to your situation and inpenetrable to others.

メーリングリストへの問い合わせ

Ask for help on the Plone setup list. Be sure to:

  • Provide relevant source code for your customizations that are part of the problem.
  • Describe the exact configuration, software versions, migration history, error messages and so on.

バグ報告

Once you have investigated, analyzed, identified and confirmed the cause of your problem and you are convinced it's a bug (rather than an X-file), go to the appropriate bug tracker and report it:

Do not use the bug trackers to ask for help. First analyze your problem and assert that it's a bug before you report it.

6. バージョン固有の移行手順とヒント

In addition to the general procedure described in the previous sections, this section provides version-specific procedures and tips.

6.1. Plone 1.0 から 2.0 へのアップグレード

Version-specific procedures and tips for migrating Plone 1.0 to 2.0.

The changes made to Plone between 1.0 to 2.0 are fairly complex. Before migrating you can read this document to understand the potential impact migrating will have on your website. We suggest to follow standard practices: backup your Products and Data.fs file(s), do the actual migration on a test instance., etc. Another note is that Plone's migration are probably not perfect - this is hard to guarantee, since we can't predict just how you have changed your system.

If you have a big site running Plone and want a painless transition to the much-improved version 2.0, we suggest that you hire a company that can do the migration properly for you. Send a mail to the Plone Developer mailing list, and we can recommend a company in your area if needed.

The migration tool handles most cases, but your mileage may vary. Heavily customized sites should factor in some time to do the transition.

2.0への移行にともなう副作用

  • PloneのCSS が大幅に変わりました。
  • Ploneのテンプレートも大幅に変わりました。
  • Plone 2.0 Tools Tools for Plone have changed
  • Plone 2.0 Group User Folder the User Folder for Plone has changed
  • See the What's New in Plone 2.0 Guide for more information about what has changed.

テンプレート/CSS の変更点

The templates and CSS have been refactored and reorganized to be leaner, more efficient and more logically laid out. The CSS class names have been changed to be consistent and to provide easier customization. Therefore, if your site customized the templates or CSS, you will have to examine how your changes are affected by the new templates and CSS.

  • ploneDeprecated.css
  • About the tableless layout
  • base_properties vs. stylesheet_properties
  • Form changes: New Forms Style and How to Convert from the Plone 1.0 forms format
  • CSS Nameageddon - the CSS class names have changed from Plone 1 to Plone 2

base_properties

Plone 1 shipped with a property sheet called stylesheet_properties, that enabled you to change your site in a quick and easy way.

In Plone 2, we have stripped this down a bit, and changed its name to base_properties to better reflect what it's for.

The reason for this was that the stylesheet_properties was kind of a half-way mix of color properties and CSS, and you could do much more than simple color changes with it. This complicated things for the CSS people, and thus we decided to keep the separation cleaner, and have only base properties in the variables.

It's not possible to do a perfect 1:1 mapping between the two, and you might have to resort to a few simple CSS rules to replicate what you had in Plone 1. The good news is that it's much more flexible and powerful this way.

The best approach to converting to the new scheme is to start with the existing base_properties, and move your color and border values over one by one until you have something that resembles your old layout.

用語集

lexicon in portal_catalog is set as plone_lexicon. Look at your ZCTextIndex indexes to see what lexicon they are looking for. On plone.org, we needed to rename the lexicon to zc_lexicon (or we could have recreated the ZCTextIndexes and specified whatever lexicon you have.) Even if your ZCTextIndex indexes are looking for the right index, you may benefit from re-indexing those fields.

Windows Installer

You have to uninstall previous Plone versions and delete the Plone service before you can install Plone 2 successfully on Windows XP. The service doesn't delete by itself when you uninstall.

6.2. Plone 2.0 から 2.1 へのアップグレード

Plone 2.0 から 2.1 への移行手順とヒント

移行およびバージョン番号についての注意

Plone has changed significantly infrastructure-wise with the jump from Plone 2.0 to 2.1. Plone 2.1 represents 18 months of active development and improvements, and is a much more scalable and powerful platform with the 2.1 release.

Some people are confused by the low version number increase, and mistakenly assume that it is a minor upgrade. It is not, far from it.

Up until Plone 2.1, the policy was that each of our major releases would be incremented 0.1, like a standard framework policy. We understand that this is somewhat confusing, and have since changed this policy. The Plone Team aims to release a new version roughly every 6 months, so we have moved to a policy that increases the version number by 0.5 on every significant release.

We have done this to better reflect the enormous amount of work that goes into each release, and to better illustrate what you can expect from a release.

The main point here is that even if an upgrade from 2.0 to 2.1 sounds minor, in this particular case it is not. The entire content type infrastructure has been rewritten, and all your content needs to be transferred to the new types, so there will most likely be some pain involved on some level — be it third-party products, templates that need to be re-customized, or actual bugs in the migration machinery (which have mostly been ironed out with the 2.1 and 2.1.1 releases).

移行について

Please note that it is difficult to predict how well migration will work, since we can't know just how you have changed your system. Plone is a very flexible system, but when migrating this will affect the outcome based on what you changes you have made to your system.

  • If you have a standard Plone site with simple customizations, it will likely work very well.
  • If you have installed and depend on a lot of third-party products produced by developers outside the Plone Team, it's hard to say something definite - make sure the products you depend on are certified to work with Plone 2.1.x. Special note about SpeedPack?: You should uninstall this product, as most of the improvements done in this product are now part of Plone, and as a result, it's no longer necessary (and it doesn't work on Zope 2.8).
  • If you have a big site running Plone and want a painless transition to the much-improved version 2.1, we suggest that you hire a company that can do the migration properly for you. Send a mail to the Plone Developer mailing list, and we can recommend a company in your area if needed.

The migration tool handles most cases, but your mileage may vary. Heavily customized sites should factor in some time to do the transition.

For Plone 2.5 (our next upcoming release), there are substantial improvements to the architecture that will ease migration in the future, as well as providing good tools for exporting and importing content and configurations.

Plone 2.1.2 and later releases also includes significant improvements to the migration machinery based on feedback we got from people doing migrations, so if migrating your site using the Plone 2.1 or 2.1.1 release didn't work out for you, please give the new version a try.

移行作業

Before you start the migration, you should decide what approach you want to use. There are two common ways of migrating:

  1. Migrating your site content, products and customizations in-place.
  2. Exporting your content, creating a fresh Plone 2.1 site, importing your content.

The in-place migration is more comprehensive, and hence more error-prone, especially if you have misbehaving third-party products or very old Plone instances. If your content is the most important thing for you, and you don't mind applying your configuration settings and simple customizations again, exporting all your content folders followed by an import into a clean instance might be a better approach for you. This procedure is described in the importing Plone 2.0 content into 2.1 FAQ. Please note that this should only be done if you are experiencing problems and as a last resort (or simply want to start with a clean site but keep your content) — for most people, in-place migration is the way to go.

The in-place procedure is the usual one for Plone migrations, a quick overview of the steps:

  1. If you want to upgrade from Zope 2.7 to Zope 2.8 in this transition, we advice you to stay with Zope 2.7 until you have completed the Plone part of the migration, then upgrade to 2.8. Zope 2.8 includes major changes and improvements, and trying to upgrade both Zope and Plone in the same operation is not recommended. Both Zope 2.7 and Zope 2.8 are supported platforms for Plone 2.1.x, though. As a rule of thumb, always start at the top with upgrades, and work your way down — upgrade Products, then Plone, then Zope, then Python.
  2. Make sure the third-party products you use have been updated or verified to work on Plone 2.1. Upgrading to 2.1 if the products you are using do not support it is a frustrating experience.
  3. Install the new Plone version in a clean location, you should stick with the same major version of Zope (e.g. going from Zope 2.7.3 to 2.7.5 is OK, going from 2.7.x to 2.8.x is not recommended until the Plone part of the migration is done).
  4. Move over your Data.fs and any Products / External Methods to the new instance.
  5. Start the new Zope/Plone
  6. Log in to the ZMI as a Manager user.
  7. Go to portal_migration
  8. Click the migrate button and wait for the output from the migration process. This can take a considerable amount of time depending on your site, since all content is being re-created with the new content types, and re-cataloged.

ありがちな問題

  • 見慣れない「新たな」タブがサイトのトップページにあらわれることがあります。これは、Ploneのナビゲーション構造の作成方針に変更があったことが原因です。Plone 2.1以降では、ルートにあるフォルダの内容に応じて自動的にタブを作成します。これまでのように、portal_actionツールで作成する必要はありません。この問題を修正するには、以下のいずれかを実行します。
    • portal_actionsのエントリで、ルートフォルダのみを指定するように変更します（各フォルダのプロパティタブで、それぞれ個別に可視性を設定することができます）。サイト内の奥深くに移動するタブを作っている場合以外は、これがお勧めの方法です。
    • 「サイト設定」→「ナビゲーション設定」で、タブの自動生成を無効にします。こうすると、2.0までと同じ方式でタブを管理できるようになります。
  • 閲覧権限のあるコンテンツアイテムやフォルダは、すべてナビゲーションツリーに表示されるようになりました。Plone 2.0までの仕様、つまり「公開されているフォルダのみを表示させる」ようにしたければ、「サイト設定」→「ナビゲーション設定」で変更します。
  • ショートネームが「events」あるいは「news」というアイテムがあなたのサイトのルートにあるのなら、移行前にそれらの名前を変更しておく必要があります。移行の際に同名のスマートフォルダが作成されるので、そのままにしておくと問題が発生します。
  • Plone の tar ボールの展開に WinZip を使用すると、AttributeError: referencebrowser_startupDirectory が発生することがあります。このツールは長いファイル名の扱いがまずく、その他にも問題があります。たとえば WinRAR のような別のツールを使うようにしましょう。
  • One of the problems that people run into during migration is third-party products they have installed that didn't clean up after themselves, or that left behind "dead" content when uninstalled. This can trip up the migration process. Here is a simple script that can list content with no associated product, so you can remove the defunct objects. To use it, create a Script (Python) from the ZMI add menu in the root of your Plone site, paste in the code from this file, click Save and then click the Test tab to run the script. It should list dead object locations, so you can go and delete them manually if needed: 
          portal_types = context.portal_types.objectIds()

          print "Dead Content Type Inspector"
          print

          for i in context.portal_catalog.uniqueValuesFor('portal_type'):
             if i in portal_types: continue
             print i
             results = context.portal_catalog(portal_type=i)
             for i in results:
                 print i.getURL()
             print 
             print

          return printed
  • Another error that was often encountered in Plone 2.1 and 2.1.1 was that some objects weren't converted to the new Archetypes-based types. If you get: "maximum recursion depth exceeded" on viewing your site after the migration, the folders/objects are most likely still CMF objects, not Archetypes objects. Plone 2.1.2 includes a fix that tries to work around this problem. (The reason this exists in the first place seems to be bad behaviour introduced in the Plone 2.0 Release Candidates and subsequently fixed before the 2.0 final release, but some people still have content created with the Release Candidates.) Also note that this error message can show up if you customized a 2.0 document_view template and are trying to use it with Plone 2.1.
  • If all (or some of) the migrated content are owned by the person doing the migration instead of the original author, that means that Plone was unable to look up the owner info while migrating. The cause of this is normally that your users are stored in LDAP and you haven't set up the connection before doing the migration. Another possibility is that your users are defined outside the Plone site.
  • If you don't get any images in the image views or thumbnails in the summary listings: PIL is now a dependency, and you will not get image scaling if it is not installed. Also, you need to make sure zlib (for PNG support) and libjpeg is installed before you install PIL. More information can be found here.
  • If your content column is missing on all pages, one of the portlets you have set up is broken. Some versions of Plone (including the RCs of 2.1.2) had a bug where it would just stop rendering the content column instead of giving you an error if one of your portlets break.
  • Some people are also confused about the behavior of security in 2.0 vs. 2.1: A bug in Plone 2.0 made it so that it seemed to be the case that if any folder along the path to an item was private, that item could not be viewed, regardless of its state. Workflows in Plone behave in a different way, though - allowing you to have a folder that is private, and have a published item inside it that is accessible (but the folder will be inaccessible). If you want your permissions to inherit down the path, you'll have to make some changes to the workflow, documented here. The reason this seemed to work in Plone 2.0 was a bug in the breadcrumb handling code, and the object wasn't protected there either, but erroneously seemed to be.
  • If you get the error AttributeError?: _length, you are upgrading to Zope 2.8, and you will need to call manage_convertIndexes on all catalogs that are not in the root (CMFCollector catalogs etc). Third-party products sometimes have their own catalogs, check with the product maintainer about this. See the section "Upgrading from Earlier Versions of Zope" in the file Zope-2.8.4-final/doc/FAQ.txt.
  • If LiveSearch? doesn't work or you have other symptoms that looks like the catalog isn't working properly, check out the FAQ on disappearing catalogs
  • If you get AttributeError?: toPortalTime from a third-party product, it needs to update itself to use toLocalizedTime instead. toPortalTime was deprecated in Plone 2.0, and is removed in Plone 2.1.
  • If for some reason some of the original tools are corrupted or not working properly, you can copy in fresh instances from a newly-created Plone site. I will show an example where the portal_form_controller tool is not present in the migrated site. Typically you would get AttributeError?: portal_form_controller as an error message. In this example, {Zope} represents the Zope root (for example, localhost:8080)and {Plone} represents your Plone site:
    1. Go to http://{Zope}/manage_main and log in with a Manager user.
    2. Add Plone Site from the pulldown menu
    3. Call it TempPlone?
    4. Once the Plone site is created, go to 'http://{Zope}/TempPlone/manage_main
    5. Check the box next to portal_form_controller, and click Cut at the bottom of the page.
    6. Go to http://{Zope}/{Plone}/manage_main
    7. Make sure there is no portal_form_controller in the list. If there is, delete it.
    8. Click the Paste button at the bottom of the form.
    9. Your site now has a fresh portal_form_controller from a new Plone 2.1 site, and should work properly. You can now delete the TempPlone? instance.

Additional notes

  • If you still have problems, create an issue in the issue tracker - make sure you use the Upgrade / Migration topic, and remember to search before submitting an issue to minimize duplicates. Make sure you provide as much detail as possible on your configuration and setup, so we can better help you.

Tip: How to re-customize your templates

If you have done significant changes to the Plone 2.0 templates (functionally, that is - the CSS classes are mostly the same as in 2.0), you may have to re-apply these customizations to the 2.1 templates. The best way to do this is:

  • Have one directory with the original Plone 2.0 templates
  • Compare your customized templates with the original Plone 2.0 ones (a visual diff tool is useful for this - we recommend Meld for Linux, FileMerge? (included in XCode) for Mac OS X, and WinMerge? for Windows)
  • Apply those changes to the 2.1 templates. Of course, your customizations should not touch the original Plone 2.1 files, so make sure you place your customized templates in a file system Product, or in the custom directory in portal_skins.

Postscript

This document was written as an attempt to collect all the relevant information about migrating from 2.0 to 2.1 in one location. It would be impossible without all the hard-working people in the Plone Team writing the migration code (which is a boring and complex task) in the first place, and the helpful people on the Plone Setup list, who have helped a lot of people migrate successfully. You all rock!

— Alexander Limi

6.3. Plone 2.1 から 2.5 へのアップグレード

Plone 2.1 から 2.5 への移行手順とヒント

現時点では、このバージョン移行に固有の特記事項はありません。このドキュメントに書かれている全般的な手順に従えば、特に問題は発生しないでしょう。

6.4. Plone 2.5 から 3.0 へのアップグレード

Plone 2.5 から Plone 3.0 へ、サイトやプロダクトをアップグレードする方法

6.4.1. アドオンプロダクトを Plone 3.0 に対応させる方法

Plone 3.0 ではZopeやCMF、Archetypesのバージョンがあがっています。フレームワークのバージョンがあがったということは、何らかの機能変更や機能削除があった可能性があります。ここでは、プロダクトの作者向けに、自作プロダクトをPlone 3.0に対応させる方法を説明します。

6.4.1.1. プロダクトを Plone 3.0 に対応させるための一般的な開発手法とヒント

Plone 3 で動作するようにプロダクトを更新する具体的な方法の前に、より一般的なことについて説明します。このあたりをしっかり理解しておくと、次期バージョンの Plone (3.5 や 4.0) への移行に手間取らなくなるでしょう。

プロダクトの種類にもよりますが、Plone 2.5 と Plone 3.0 の両方で動作するプロダクトを作成するのはかなり難しいでしょう。理由はいくつかありますが、最も大きな理由は次の３つです。

  • CMFにおけるワークフローの定義の方法が変わったこと
  • ポートレットの仕組みが新しくなったこと (旧バージョンのポートレットにも対応していますが、処理速度が低下します)
  • コンテンツの一部をページに組み込む手法として、新たに「ビューレット (viewlet)」が導入されたこと

そこで、次のように作業を進めることをお勧めします。

  • あなたのプロダクトが単純なものでない場合は、Plone 2.5 用と Plone 3.0 用の２種類のリリースを作成するようにしましょう。
  • ArchGenXML を用いてプロダクトを作成している場合は、UMLモデルからプロダクトを再作成することでPlone 3.0互換バージョンを作成できます。
ヒント
  • 将来のバージョンアップ (Plone 3.5 や 4.0) にも対応できるよう、以下のことを心がけましょう。
    • zopectl fg を使用して Zope をデバッグモードで立ち上げ、自作のプロダクトを通常通り使用します。そして、ログウィンドウに何か deprecation warning が出ていないかどうかを確認します。
    • plone_deprecated スキンを無効にし (こうすると、廃止予定のメソッドや CSS スタイルが無効になります)、それでもあなたのプロダクトがきちんと動作することを確認します。
その他の推奨事項
  • contentmigration プロダクトを使用すると、自作のプロダクト用の移行ツールを作成することができます。このプロダクトについての詳細は、RichDocument チュートリアルをごらんください。
  • 新しいコンポーネントの多くは、テンプレートではなくZope 3のビューを使用しています。これは、ウェブ上でportal_view_customizationsを使用してカスタマイズすることが可能です。
  • PloneのJSライブラリを直接使用することは避けましょう。そうではなく、抽象化レイヤーであるKSSを使用しましょう。その奥の実装は、今後変更される可能性があります(って言うか、きっと変わります！）。

以下の内容は、現時点では必須ではありません。しかし、将来のことを考えると、今から対応しておいたほうがいいものばかりです。

  • QuickInstallerベースのインストールではGenericSetupプロファイルを使用します。
    • manage_ methods (おそらく plone 3.5 あるいは 4.0 で廃止されます) ではなく events を使用します。
  • パッケージング
    • Zopeプロダクト形式ではなく、pythonパッケージを使用します。
    • そのパッケージをeggs形式で公開し、Python Cheese Shopにも登録します。
    • 新しいパッケージを作成する際にはPython Pasteを使用します。
  • 提案: ploneit あるいは ploneout を使用すると、開発環境や運用環境を簡単にコピーできるようになります。

pythonパッケージの使用法についての詳細な説明は、Guide to Python packages reference guideをごらんください。

6.4.1.2. CMFCore.permissions のインポート方式の変更

最新のCMFでは、permissionモジュールのインポート方法が変更されました。ここでは、新旧両方の方式に対応させるための手法を説明します。

Zopeの起動時に表示されるエラーメッセージの例 

  XXX あとでサンプルを追加

この原因は、

permissionsモジュールにアクセスするための次のコードです。これは、通常は init.py の中にあります。 

  from Products.CMFCore import CMFCorePermissions

これを新しい方式でも動作する (もちろん今までの方式でも動作する) ようにするには、次のように書き換えます。 

  try: # New CMF  
      from Products.CMFCore import permissions as CMFCorePermissions 
  except: # Old CMF  
      from Products.CMFCore import CMFCorePermissions

これで、あなたのプロダクトで複数のバージョンに対応できるようになります。try/except が必要なのは、Plone 2.1をサポートしなければならない場合のみであることに注意しましょう。Plone 2.5以降を対象とするのなら、上の例の「New CMF」の部分だけで対応できます。

この変更の実例は、Poi のチェンジセット40594をごらんください。

6.4.1.3. Transactionモジュールが、Archetypesに暗黙的に組み込まれることがなくなった

Archetypes 1.3 および 1.4 では、Zorp 2.7 で起こる問題への回避策としてtransactionをmainモジュールに組み込んでいました。Zope 2.7 のサポートは終了しているので、Archetypes 1.5 (Plone 3.0 で用いられているバージョン) ではこの回避策は仕込まれないようになっています。あなたのコードの変更点を次に示します。

Zopeの起動時に表示されるエラーメッセージの例 

  from Products.Archetypes import transaction
  ImportError: cannot import name transaction

Archetypesが自動的にtransactionをインポートすることはなくなったので、もしこれを使用している場合は、自作のモジュール側で明示的にインポートしておく必要があります。 

  from Products.Archetypes import transaction

となっているところを、すべて 

  import transaction

と変更してください。実際の例としてはPoi のチェンジセット 40594が参考となるでしょう。

6.4.1.4. get_transaction モジュールの名前の変更

Zopeでトランザクションを取得する方法が変更され、最近のリリースでは以前の方式が非推奨扱いとなっていました。Zope 2.10.x (Plone 3.0 の動作環境) では以前の方式が完全に廃止されているので、コードを適切に修正する必要があります。

エラーメッセージの例 

  NameError: global name 'get_transaction' is not defined

完全なトレースバックは、このようになります。サブトランザクションを使用しているプロダクトをインストールしようとしたときなどに、このようなことが起こりえます。 

  2007-04-12 23:12:01 ERROR Zope.SiteErrorLog http://localhost:8080/nu/portal_quickinstaller/installProducts
  Traceback (innermost last):
  Module Products.CMFQuickInstallerTool.QuickInstallerTool, line 381, in installProduct
   - __traceback_info__: ('Poi',)
  Module Products.ExternalMethod.ExternalMethod, line 231, in __call__
   - __traceback_info__: ((<PloneSite at /nu>,), {'reinstall': False}, (False,))
  Module /Users/limi/Projects/Plone/3.0/Products/Poi/Extensions/Install.py, line 65, in install
  NameError: global name 'get_transaction' is not defined
  /Users/limi/Projects/Plone/3.0/Products/CMFQuickInstallerTool/QuickInstallerTool.py:409:
  DeprecationWarning: This will be removed in ZODB 3.7:
  subtransactions are deprecated; use sp.rollback() instead of transaction.abort(1), 
  where `sp` is the corresponding savepoint captured earlier
  transaction.abort(sub=True)

これを回避するには、 

  get_transaction().commit(1)

という箇所を以下のように変更します。 

  transaction.commit(1)

(コード中の (1) の部分はそのままにしておきます。もし何も指定されていない場合は、そのまま省略しておきます)

transactionモジュールをインポートしていないのなら、ファイルの先頭に import transaction を追加する必要があるかもしれません。

実際の例は、Poi のチェンジセット 40594におけるInstall.pyの変更点を見てみましょう。

6.4.1.5. ContentFactoryMetadata? の廃止

CMF では、最近これを非推奨扱いにしていましたが、Plone 3.0 でとうとう実際に廃止されました。新しい方式に対応させるやりかたを説明します。

エラーメッセージの例 

  Error Type: exceptions.ImportError
  Error Value: cannot import name ContentFactoryMetadata

この原因は何でしょう？ おそらく、あなたのコード中に 

  from Products.CMFCore.TypesTool import ContentFactoryMetadata

という部分があるはずです。これを以下のように変更しましょう。 

  from Products.CMFCore.TypesTool import FactoryTypeInformation

このコードは、Plone 2.1 以降で正しく動作します。

実際の変更の例はDataGridField のチェンジセット 7901が参考になるでしょう。

6.4.1.6. ワークフローを、GenericSetupプロファイルを用いるように変更する

Plone 3.0でワークフローをインストールするには、CMFのGenericSetupプロファイルを使用する必要があります。それ以外の方法によるインストールには、残念ながら対応していません。CMFのアーキテクチャに変更があったため、両方の方式を同時にサポートすることが不可能になったのです。

GenericSetupによるワークフローのインストールを使用すると、そのプロダクトは Plone 2.5 以降でしか動作しなくなります。もし Plone 2.1/2.0 でも動作させる必要があるのなら、２種類のリリース/ブランチを作成する必要があります (ただし、Plone 3.0がリリースされた時点で Plone 2.1/2.0 のサポートは終了します)。

GenericSetupを使わずにワークフローをインストールしようとしたときのエラーメッセージの例 

  ImportError: cannot import name addWorkflowFactory

既存のワークフローをGenericSetupに対応させる最も簡単な方法は、次のとおりです。

  • まずPlone 2.5にプロダクト (とワークフロー) をインストールします。
  • ZMI で portal_setup ツールを使い、現在のサイトのプロファイルのスナップショットをエクスポートします。
    • エクスポートタブをクリックします。
    • 設定をエクスポートしたいパーツ (今回の場合はWorkflow Tool) を選択します。
    • Export Selected Steps ボタンをクリックします。
    • setup_tool-20070424225827.tar のような名前の tar ファイルが出来上がります。
  • tar ファイルを展開し、出来上がったファイルやディレクトリをあなたのプロダクトの profiles/default/ ディレクトリ以下に配置します。
  • あなたのプロダクトのものではないワークフローディレクトリ workflow/ を削除し、workflows.xml を編集してあなたのワークフローの情報のみを含めるようにします。例としては Poi のチェンジセット 41071をごらんください。
  • Extensions にある、古い形式の'.py'でのワークフロー定義を削除します。しかしそのスクリプト自体は残しておきましょう。あとでプロファイルを定義する際に必要となります。
  • プロダクトのルートディレクトリ配下に configure.zcml というファイルを追加し、デフォルトのプロファイルを登録します。Poi の configure.zcmlを参考にするといいでしょう。
  • Extensions/Install.py から余計なコードを削除し、GenericSetupを起動するお決まりのコードを追加します。Poi のチェンジセット 41071を参考にするといいでしょう。

この手順は、GenericSetupへの移行をめざすコードならなんにでも適用できます。たびたび例にあげるPoiでは、カタログメタデータなどの多くの内容をGenericSetupプロファイルに移行しました。その結果、Install.pyで行っていた処理の大半を追い出すことができました。

6.4.1.7. Membershipツールによるユーザやグループの検索が非推奨に

portal_membershipツールやportal_groupsツールによるユーザやグループの検索が非推奨となりました。PASの検索機能を直接使用するか、PlonePASのpas_searchビューを使用しましょう。

XXX 例が必要。(Wichert)

6.4.1.8. ポートレットの構造の変更

Plone 3.0では、ポートレットはもはや単なるページテンプレートではなくなりました。振る舞いやロジックを内包したオブジェクトとなったのです。ポートレット単位のキャッシュ機能などを組み込むこともできるでしょう。

Zope 3 のコンポーネントの仕組みを用いて、ポートレットが実装しなおされました。独自のポートレットを作成している場合は、可能なら plone.app.portlets を使用するように変更しましょう。

いままでのポートレットも（クラシックポートレットとして）対応しています。また、ポートレットの管理画面上で、古い形式のポートレットを移行する機能もあります。古い形式のポートレットをそのまま使用し続けると、サイトのパフォーマンスが悪化することに注意しましょう。

XXX 例が必要。(Martin?)

6.4.1.9. main_template now uses Zope 3 viewlets

Plone 3 has switched to use Zope 3 viewlet components instead of the old macro include approach. Any customizations of main_template.pt or header.pt will need to be updated to use the new approach.

If have previously shipped customized versions of templates like header.pt, viewThreadsAtBottom.pt or global_contentmenu.pt to get things into the page, please switch to viewlets instead, as it makes it much easier for multiple products to co-exist without stepping on each others changes.

例が必要。(Florian)

6.4.1.10. Plone 3 does not create member folders by default

With release 3.0, member folders are optional, and not created by default. This means that you can't rely on member folders to store data in or in any other way assume that there will be a members folder present.

While this was always considered bad practice, it's now official. Don't do it. :)

6.4.1.11. Plone Tableless theme no longer exists

The languishing tableless version of the Plone default theme has finally been removed from Plone 3.0.

For those of you who desire a tableless implementation of the default skin, please backport the markup changes to the new main_template.

NuPlone? (the new theme in Plone 3.0) is a table-less alternative that we hope you like.

6.4.1.12. Document Actions now use Zope 3 viewlets

If you were modifying or shipping custom templates for the document actions area of a Plone page, now's the time to stop.

The new approach uses viewlets, and its default position has also been moved to the bottom of the page. It also defaults to a text-based representation instead of the icons that it was using earlier, since document actions are often too abstract to create good icons for.

6.4.1.13. Products installing workflows may need to add permissions

If your product wants to make use of the new "Editor" role that ships with Plone 3, you will have to add explicit permissions to any workflows you add.

The new "Editor" (aka. "Can Edit" on the Sharing page) in Plone 3.0 makes it easy to let people collaborate on content authoring. In some cases, editing also means the ability to add new objects inside the object people are editing.

For this to work, third party content types that add custom workflows will have to either use one of the standard "add content" permissions or explicitly give Editor the Add portal content role.

See Ticket #6265 for the changeset and full explanation.

6.4.1.14. Indexes declared in Archetypes schemata need to be moved to GenericSetup?

If you have declared indexes or metadata directly on the Archetypes field declarations, and you are using GenericSetup? to install your types/FTIs, you will need to move them to GenericSetup?.

This applies if you have moved from using install_types() in Extensions/Install.py, to installing new content types/FTIs with GenericSetup? using a types.xml import step.

For each field that specifies an index, like this example from PoiIssue.py r40594 : 

  StringField(
      name='issueType',
      index="FieldIndex:schema",
      widget=SelectionWidget(
          label="Issue type",
          description="Select the type of issue.",
          label_msgid='Poi_label_issueType',
          description_msgid='Poi_help_issueType',
          i18n_domain='Poi',
      ),
      enforceVocabulary=True,
      vocabulary='getIssueTypesVocab',
      required=True
  ),

…you need to move the creation to catalog.xml with GenericSetup?. If there is index="FieldIndex?", that means you need a new index, of type FieldIndex?, with the name being the name of the accessor method: 

  <index name="getIssueType" meta_type="FieldIndex">
    <indexed_attr value="getIssueType"/>
  </index>

If there is also :schema or :metadata, e.g. index="FieldIndex:schema", you also need a metadata column: 

  <column value="getIssueType"/>

This is necessary because the schema does not really exist at install time, so there is no way GenericSetup? can inspect it and configure new indexes. This was a bad design from the start, as portal-wide indexes do not belong in type-specific schemata anyway.

6.4.1.15. The "Sharing" tab is now a global action

You should no longer have a 'sharing' action in the portal_types entry for a custom content type

The "Sharing" tab now points to the @@sharing view, and is defined as a global action in the object category. If you have a custom content type and you have set up the local_roles action, which would normally be pointing to the folder_localrole_from template, you should remove it. It will be removed from existing, installed types during migration.

If you do not remove the action, the user will see two "Sharing" tabs.

For an example of the canonical set of actions and aliases, see the GenericSetup definition of the Document FTI. Of course, you may not need the References, History or External Edit actions in your own types.

6.4.1.16. Multi page schemas

By default, Archetypes fields in different schemas in Plone 3.0 will be loaded all at once, without page reloads between the 'schematas'.

In Plone 3.0, all fields from all schematas will be loaded at once. If you depend on your schematas (fieldsets) to be processed one page after the other, you'll need to mark your Archetypes content type that uses it (not the schema itself) with the IMultiPageSchema interface.

The interface lives in Products.Archetypes.interfaces.IMultiPageSchema. The code to mark your content type would look like this: 

from zope import interface
from Products.Archetypes.interfaces import IMultiPageSchema
# ...
interface.alsoProvides(MyContentType, IMultiPageSchema)