beginning docs for 3.0

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`)