From 2597e0dd9128d6322ef443c1fea012c13d8a4a4f Mon Sep 17 00:00:00 2001 From: Daniel Rudolf Date: Mon, 2 Nov 2015 19:14:07 +0100 Subject: [PATCH] Move upgrade instructions from inline docs to README.md in a more generic form --- README.md | 18 ++++++++++++++++-- content-sample/index.md | 40 ---------------------------------------- 2 files changed, 16 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 2f31af3..ab8fd1f 100644 --- a/README.md +++ b/README.md @@ -38,6 +38,20 @@ $ curl -sS https://getcomposer.org/installer | php $ php composer.phar install ``` +Upgrade +------- + +Upgrading Pico is very easy: You just have to replace all of Picos files - that's it! Nevertheless you should *always* create a backup of your Pico installation +before upgrading. + +Pico follows [Semantic Versioning 2.0](http://semver.org) and uses version numbers like `MAJOR`.`MINOR`.`PATCH`. When we update... + +- the `PATCH` version (e.g. `1.0.0` to `1.0.1`), we made backwards-compatible bug fixes. It's then sufficient to extract [Picos latest release][LatestRelease] to your existing installation directory and overwriting all files. +- the `MINOR` version (e.g. `1.0` to `1.1`), we added functionality in a backwards-compatible manner, but anyway recommend you to "install" Pico newly. Backup all of your files, empty your installation directory and install Pico as elucidated above. You can then copy your `config/config.php` and `content` directory without any change. If applicable, you can also copy the folder of your custom theme within the `themes` directory. Provided that you're using plugins, also copy all of your plugins from the `plugins` directory. +- the `MAJOR` version (e.g. `1.0` to `2.0`), a appropriate upgrade tutorial will be provided. + +Upgrading Pico 0.8 or 0.9 to Pico 1.0 is a special case. The new `PicoDeprecated` plugin ensures backwards compatibility, so you basically can follow the above upgrade instructions as if we updated the `MINOR` version. However, we recommend you to take some further steps to confine the neccessity of `PicoDeprecated` as far as possible. For more information about what has changed with Pico 1.0 and a step-by-step upgrade tutorial, please refer to the [upgrade page of our website](http://picocms.org/upgrade.html). + Run --- @@ -62,7 +76,7 @@ Access Pico from . Getting Help ------------ -You can read the [wiki][Wiki] if you are looking for examples and read the inline-docs for more development information. +You can read the [Wiki][] if you are looking for examples and read the inline-docs for more development information. If you find a bug please report it on the issues page, but remember to include as much detail as possible, and what someone can do to re-create the issue. @@ -73,7 +87,7 @@ Contributing Help make PicoCMS better by checking out the GitHub repository and submitting pull requests. -If you create a plugin please add it to the Wiki. +If you create a plugin please add it to the [Wiki][]. Plugins + Wiki -------------- diff --git a/content-sample/index.md b/content-sample/index.md index 3adb7c8..a4eaf08 100644 --- a/content-sample/index.md +++ b/content-sample/index.md @@ -267,46 +267,6 @@ setting `$config['rewrite_url'] = true;` in your `config/config.php`. 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. %base_url%?sub/page) 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: describe how to replace `PicoExcerpt` -* TODO: Removing various empty `index.html` files; check accessibility! -* TODO: Describe new features that are important for users... e.g. `%meta.*%` - ## Documentation For more help have a look at the Pico documentation at