Browse Source

Add UPGRADE section to docs

This is still work in progress
Daniel Rudolf 9 years ago
parent
commit
638638f5a4
1 changed files with 40 additions and 1 deletions
  1. 40 1
      content-sample/index.md

+ 40 - 1
content-sample/index.md

@@ -234,7 +234,7 @@ You're a plugin developer? We love you guys! You can find tons of information
 about how to develop plugins at http://picocms.org/plugin-dev.html. If you'd
 about how to develop plugins at http://picocms.org/plugin-dev.html. If you'd
 developed a plugin for Pico 0.9 and older, you probably want to upgrade it
 developed a plugin for Pico 0.9 and older, you probably want to upgrade it
 to the brand new plugin system introduced with Pico 1.0. Please refer to the
 to the brand new plugin system introduced with Pico 1.0. Please refer to the
-[Upgrade section of the docs](http://picocms.org/plugin-dev.html#upgrade).
+[upgrade section of the docs][PluginUpgrade].
 
 
 ## Config
 ## Config
 
 
@@ -267,6 +267,44 @@ setting `$config['rewrite_url'] = true;` in your `config/config.php`.
         try_files $uri $uri/ /pico/?$uri&$args;
         try_files $uri $uri/ /pico/?$uri&$args;
     }
     }
 
 
+## Upgrading to Pico 1.0
+
+We worked hard to make the upgrade process to Pico 1.0 as easy as possible -
+and we think we made the grade. Usually you don't have to consider anything
+special, nevertheless you should create a backup of your Pico installation
+before upgrading.
+
+The first step is to delete all of Picos files except for your `content`
+directory, `config.php` (or `config/config.php`) and, if applicable, the
+directory of your custom theme. Provided that you're using plugins, also keep
+the `plugins` directory. You can then upload Pico 1.0 to your installation
+directory. Please refer to the websites of the plugins you're using to get
+updates for them.
+
+The new `PicoDeprecated` plugin ensures backward compatibility to Pico 0.9 and
+older. The plugin is disabled by default, but gets automatically enabled as
+soon as a old plugin is loaded. We will maintain backward compatibility for
+a long time, however, we recommend you to take the following steps to confine
+the neccessity of `PicoDeprecated` to old plugins. If you don't use plugins or
+upgraded all plugins to be compatible to Pico 1.0, you must take these steps.
+
+If you're a plugin developer, please refer to the new development docs,
+particularly the [plugin upgrade section][PluginUpgrade].
+
+* Move your `config.php` to the new `config/` directory.
+* URL Rewriting became optional in Pico 1.0. If you don't use the `.htaccess`
+  file provided by Pico, you must update your rewriting rules to let the
+  webserver rewrite internal links (e.g. `index.php?sub/page`) correctly.
+  You musn't update your markdown files or custom Twig templates if you keep
+  URL rewriting enabled. Otherwise you have to rectify all internal links in
+  markdown files (e.g. <code>&#37;base_url&#37;?sub/page</code>) and your
+  custom Twig templates (e.g. (e.g. `{{ "sub/page"|link }}`)).
+* Pico 1.0 doesn't parse the contents of all pages anymore. This can be put
+  down to the massive performance impact, but leads to the removal of the
+  generation of auto-generated excerpts.
+  TODO: describe how to force enable/disable `PicoExcerpt` and `PicoParsePagesContent`
+* TODO: Removing various empty `index.html` files; check accessibility!
+
 ## Documentation
 ## Documentation
 
 
 For more help have a look at the Pico documentation at
 For more help have a look at the Pico documentation at
@@ -274,3 +312,4 @@ For more help have a look at the Pico documentation at
 
 
 [Twig]: http://twig.sensiolabs.org/documentation
 [Twig]: http://twig.sensiolabs.org/documentation
 [Markdown]: http://daringfireball.net/projects/markdown/syntax
 [Markdown]: http://daringfireball.net/projects/markdown/syntax
+[PluginUpgrade]: http://picocms.org/plugin-dev.html#upgrade