diff options
| -rw-r--r-- | debian/NEWS | 9 | ||||
| -rw-r--r-- | doc/roadmap.mdwn | 23 | ||||
| -rw-r--r-- | doc/tips/upgrade_to_3.0.mdwn | 72 |
3 files changed, 92 insertions, 12 deletions
diff --git a/debian/NEWS b/debian/NEWS index a7a145d9b..1c9763d1a 100644 --- a/debian/NEWS +++ b/debian/NEWS @@ -1,3 +1,12 @@ +ikiwiki (3.0) unstable; urgency=low + + The 3.0 release of ikiwiki changes several defaults and makes + some transitions. You will need to modify your wikis to work with + ikiwiki 3.0. A document explaining the process is available + in </usr/share/doc/ikiwiki/html/tips/upgrade_to_3.0.html> + + -- Joey Hess <joeyh@debian.org> Tue, 23 Dec 2008 16:14:18 -0500 + ikiwiki (2.62) unstable; urgency=low TexImg standard preamble changed diff --git a/doc/roadmap.mdwn b/doc/roadmap.mdwn index 9ed5742eb..c85c6de5b 100644 --- a/doc/roadmap.mdwn +++ b/doc/roadmap.mdwn @@ -7,10 +7,7 @@ This is the roadmap for ikiwiki development. Released 29 April 2006. -The 1.x series changed a great deal over the more than 50 releases in its -lifetime. It is now in maintenance mode, only security issues or really bad -bugs will be fixed in 1.x going forward. 1.x will stop being supported with -the release of 3.0. +The 1.x series is no longer supported. ---- @@ -32,20 +29,18 @@ the release of 3.0. Released 30 April 2007. -The 2.x series is expected to undergo continuing development for some time, -adding improvements and new features, but avoiding changes that break -backwards compatability. +The 2.x series is now in maintenance mode. Only security fixes and fixes for +really bad bugs will be applied going forward. ---- # 3.0 -Version 3.0 will be an opportunity to make significant transitions. +Version 3.0 is an opportunity to make significant transitions, and also adds +many new features. -* Default to using `prefix_directives`. -* Default to using `aggregateinternal`. -* Remove deprecated prefs form settings for `allowed_attachments` and - `locked_pages`. +* See [[tips/upgrade_to_3.0]] for the steps you will need to follow + when upgrading to this version. * Finalise a new version of the plugin API, exporting additional commonly used functions from IkiWiki.pm. See [[todo/firm_up_plugin_interface]] @@ -54,6 +49,10 @@ improvements, far too many to list here. Release is planned for fall^Wlate, 2008. +The 3.x series is expected to undergo continuing development for some time, +adding improvements and new features, but avoiding changes that break +backwards compatability. + ---- # future goals diff --git a/doc/tips/upgrade_to_3.0.mdwn b/doc/tips/upgrade_to_3.0.mdwn new file mode 100644 index 000000000..6c74d4fc9 --- /dev/null +++ b/doc/tips/upgrade_to_3.0.mdwn @@ -0,0 +1,72 @@ +Version 3.0 of ikiwiki makes some significant configuration changes, which +you will need to deal with when upgrading from ikiwiki 2.x. + +[[!toc ]] + +# moving settings from Preferences page + +The admin preferences page used to have settings for allowed attachments, +locked pages, and banned users. These three settings have moved to the +setup file: + + allowed_attachments => "", + locked_pages => "", + banned_users => "", + +If you have not yet upgraded to ikiwiki 3.0, you can look at the admin +preferences page to see if any of these values is shown there, and copy +them into the setup file. + +## setup file format change + +The layout of the setup file changed in a significant way in version 2.60 +of ikiwiki. If you have not changed yours to the new format, now would be a +good time to do so. Some new features, like the [[plugins/websetup]] interface, +need the new format setup file. + +You can convert old setup files into the new format by running +`ikiwiki-transition setupformat your.setup` + +## prefix directives + +In 3.0, the syntax ikiwiki uses for [[directives|ikiwiki/directive]] has +changed, requiring that the directive start with a bang: + + \[[!directive ...]] + +If you would like to keep the old syntax, it is still supported, add the +following to your setup file: + + prefix_directives => 0, + +But it's not hard to convert your wiki to the new syntax. You can use +[[ikiwiki-transition]]. It will convert preprocessor directives in all +files given on the command line. To convert an entire wiki: + + find wikidir/ -type f -name '*.mdwn' -print0 | xargs -0 ikiwiki-transition prefix_directives + +Be sure to modify the find to list all pages in the wiki if you're using +other markup than markdown. You will probably want to commit the changes +when you're done too. + +## aggregateinternal + +If your wiki uses the [[aggregate|plugins/aggregate]] plugin, it will start +to aggregate feeds to special "internal" pages. + +If you don't want this change, you can add the following to your setup +file: + + aggregateinternal => 0, + +Otherwise, follow this procedure to upgrade a wiki using the aggregate plugin: + +1. Update all [[PageSpecs|ikiwiki/PageSpec]] that refer to the aggregated + pages -- such as those in inlines. Put "internal()" around globs + in those PageSpecs. For example, if the PageSpec was `foo/*`, it should + be changed to `internal(foo/*)`. This has to be done because internal + pages are not matched by regular globs. +2. Use [[ikiwiki-transition]] to rename all existing aggregated `.html` + files in the srcdir. The command to run is + `ikiwiki-transition aggregateinternal your.setup`, +3. Refresh the wiki. (`ikiwiki -setup your.setup -refresh`) |