1
2
3
4
5
6
7
8
9
10
|
version=pmwiki-2.3.36 ordered=1 urlencoded=1
author=Petko
charset=UTF-8
csum=[[Site.EditForm]], sortable, rowspan (+629)
name=PmWiki.Upgrades
post= Save
rev=118
targets=PmWiki.PmWiki,PmWiki.UpgradingFromPmWiki1,PmWiki.Upgrades,PmWiki.ReleaseNotes,PmWiki.BackupAndRestore,PmWiki.Download,PmWiki.SiteAnalyzer,PmWiki.LocalCustomizations,PmWiki.Troubleshooting,Site.Site,SiteAdmin.SiteAdmin,PmWiki.BasicVariables,PmWiki.WikiWords,PmWiki.EditVariables,PmWiki.Links,PmWiki.PageLists,PmWiki.SkinTemplates,PmWiki.AuthUser,PmWiki.ChangeLog,PmWiki.PageVariables,Site.PageActions,Site.EditForm,Site.PageNotFound,PmWiki.LayoutVariables,Cookbook.PageListMultiTargets,PmWiki.Functions,PmWiki.Version
text=(:Summary:How to upgrade an existing PmWiki installation:)%0a[[PmWiki]] is designed to make it easy to upgrade the PmWiki software without affecting your existing data files or installation. For most upgrades, you simply copy the files in the new release over your existing installation.%0a%0a>>frame padding=5px%3c%3c%0a'''Note for PmWiki 1.0 sites:''' Upgrading from 1.0.x to 2.0 requires more than simply copying the 2.0 software over the 1.0 installation. See [[(PmWiki:)Upgrading From PmWiki 1]] for more details.%0a>>%3c%3c%0a%0a%25commentout-pmwikiorg%25 ''Note: this page may have a more recent version, see PmWiki:Upgrades.''%0a%0a[[#gen]]%0a!! Generic instructions %0a%0a!!! 1. Read the release notes%0aPlease read carefully the [[(PmWiki:)ReleaseNotes]] before performing an upgrade, about the changes between your previous version and the new one. See if there are any significant changes or preparation tasks that must be handled before performing the upgrade.%0a%0a!!! 2. Backup%0aIt's ''always'' a good idea to have a [[(PmWiki:)backup( and Restore)]] copy of your existing PmWiki installation before starting. You can copy the entire directory containing your existing installation, or you can just make copies of the ''wiki.d/'' directory and any other local customization files you may have created (e.g., ''@@config.php@@'', ''@@localmap.txt@@'', etc.).%0a%0a!!! 3. Download and extract%0aDownload the version of PmWiki that you want from the [[(PmWiki:)download]] page.%0a%0aExtract the tar image using @@tar -xvzf ''tgzfile''@@, where ''tgzfile'' is the tar file you downloaded above. This will create a @@pmwiki-x.y.z@@ directory with the new version of the software.%0a%0a!!! 4. Copy%0aCopy the files in @@pmwiki-x.y.z@@ over the files of your existing PmWiki installation. For example, if your existing PmWiki installation is in a directory called ''pmwiki'', then one way to copy the new files over the existing ones is to enter the command:%0a%0a->@@cp -a pmwiki-x.y.z/. pmwiki@@%0a%0aNote that BSD systems will not have the -a option as a command-line argument for ''cp'', but that's okay, since it's just shorthand for ''cp -dpR'', so use that instead of ''-a''.%0a%0aSome environments have an alias established for ''cp'' that enable interactive prompts before overwriting a file. To work around this specify the absolute path to ''cp'', such as ''/bin/cp''.%0a%0aOn (some) [=FreeBSD=] servers and Mac OS X systems you need to use %0a%0a->@@cp -Rpv pmwiki-x.y.z/. pmwiki@@%0a%0aAlternatively, you can use @@rsync@@:%0a%0a->@@rsync --dry-run -ahv --stats pmwiki-x.y.z/ pmwiki/@@%0a%0aThis will perform a trial run with no changes made but will show which files would be updated. To perform the actual update, remove the @@--dry-run@@ option.%0a%0a!!! 5. Update customisations and recipes%0aThat's it! Your base PmWiki installation is complete.%0a%0aNow use the [[PmWiki:Site Analyzer]] to determine which recipes could be updated to the most recent version.%0a%0aUnless you have made customizations to the ''@@pmwiki.php@@'' script or to the files in ''@@scripts/@@'', your PmWiki installation should continue to run correctly! (Changes to these files are {+not+} recommended).%0a%0a([[Local customizations]] should go in ''@@local/config.php@@'', ''@@pub/css@@'', and ''@@pub/skins/@@''@@yourskinname@@)%0a%0a'''Note''': Additional tips can be found on the [[PmWiki:Troubleshooting]] page.%0a%0a%0a[[#v21v22]]%0a!! Upgrading from version 2.1.27 to 2.2.0%0a%0aBetween the stable versions 2.1.27 and 2.2.0 there are a number of additions. Some of them may need changes to local config files or to wiki pages, and they are outlined here. For the full list of changes see [[ReleaseNotes#v220|the release notes]].%0a%0aIf you are upgrading from a 2.2.beta version, your wiki may already include these features.%0a%0a* Some pages that were formerly in the [[Site]].* group are now in a separate read-protected [[SiteAdmin]].* group: @@Site.AuthUser@@, @@Site.AuthList@@, @@Site.NotifyList@@, @@Site.Blocklist@@, and @@Site.ApprovedUrls@@. If upgrading from an earlier version, PmWiki will prompt to automatically copy these pages to their new location if needed. If a site wishes to continue using the old @@Site.*@@ group for these pages, simply set to @@config.php@@ %25hlt php%25@@$SiteAdminGroup = $SiteGroup;@@%0a%0a* To authorize reading or editing in protected areas, the former password @@"nopass"@@ should now be written as @@"@nopass"@@.%0a%0a* [[WikiWords]] are now disabled by default. To re-enable them, set either $LinkWikiWords or $EnableWikiWords to 1.%0a%0a* The $ROSPatterns variable has changed -- replacement strings are no longer passed through %25hlt php%25@@FmtPageName()@@ i.e., it must now be done explicitly.%0a%0a* [[Links|Page links]] inside included pages, sidebars, headers or footers are now treated as relative to the page where they are written, instead of the page where they appear. For example, in @@Site.SideBar@@, always set the group in a wikilink like %25pmhlt%25[@[[Main/HomePage]]@] or with a page variable [@[[{*$Group}/HomePage]]@], because a link [@[[HomePage]]@] will point to a page @@Site.HomePage@@.%0a%0a* [[PageLists]]%0a** Spaces no longer separate wildcard patterns -- use commas. %0a** %25pmhlt%25[@{$PageCount}, {$GroupCount}, {$GroupPageCount}@] variables used in pagelist templates are now [@{$$PageCount}, {$$GroupCount}, {$$GroupPageCount}@].%0a** The directive no longer accepts parameters from urls by default. In order to have it accept such parameters (which was the default in 2.1 and earlier), add a %25pmhlt%25[@request=1@] option to the [@(:pagelist:)@] directive.%0a%0a* [[Skin templates]] are now required to have %25hlt html%25@@%3c!--HTMLHeader-->@@ and @@%3c!--HTMLFooter-->@@ directives. %0a%0a* Authentication using Active Directory is now simplified, see [[PmWiki.AuthUser]].%0a%0a%0a[[#v220]]%0a!! Upgrading from version 2.2.0 to 2.2.145%0a%25commentout-pmwikiorg%25 ''Note: this page may have a more recent version, see PmWiki:Upgrades.''%0a%0aSome additions since version 2.2.0 may need changes to local config files or to wiki pages, and they are outlined here. For the full list of changes see [[ReleaseNotes|release notes]] and [[change log]].%0a%0a* Version 2.2.10: $EnableRelativePageVars was changed to enabled by default, and it affects [[PageVariables]] from included pages, sidebars, headers and footers.%0a** The form %25pmhlt%25[@{*$var}@] refers to "the currently browsed page" while [@{$var}@] without an asterisk refers to "the physical page where the PageVar is written".%0a** %25red%25 Pages that are designed to work on "the currently browsed page" should switch to using %25pmhlt%25[@{*$FullName}@] instead of [@{$FullName}@]. %25%25 Administrators should especially check any customized versions of [[Site.PageActions]], [[Site.EditForm]], [[Site.PageNotFound]], @@SideBar@@ pages, $GroupHeaderFmt, $GroupFooterFmt, [[Page lists]] in sidebars, headers, and footers. See [[Page variables#specialreferences|Special references]].%0a** If your wiki heavily relies on the previous behavior, you can revert to it, see $EnableRelativePageVars.%0a%0a* Version 2.2.35: Important change for international wikis: the %25hlt php%25@@XLPage()@@ function no longer loads encoding scripts such as @@xlpage-utf-8.php@@. When you upgrade, you need to include those scripts from @@config.php@@, before the call to %25hlt php%25@@XLPage()@@: [@%0a include_once("scripts/xlpage-utf-8.php"); # if your wiki uses UTF-8%0a XLPage('bg','PmWikiBg.XLPage');%0a@]%0a%0a%0a[[#v22v23]]%0a!! Upgrading from version 2.2.145 to 2.3.0%0a%25commentout-pmwikiorg%25 ''Note: this page may have a more recent version, see PmWiki:Upgrades.''%0a%0a[[ReleaseNotes#v230|Version 2.3.0]] requires PHP 5.3 or more recent. The new version includes a number of new features, some of which were previously provided by recipes. %0a%0aHere are the things to review when upgrading:%0a%0a* If you previously used Cookbook:PageListMultiTargets, please disable it when you upgrade. The same functionality is now available in the core.%0a* For PHP 8.1, the function %25hlt php%25@@strftime()@@ has been deprecated. PmWiki 2.3.0 provides a replacement function @@PSFT()@@, see PmWiki:Functions#PSFT.%0a* The @@RecentChanges@@ pages now store in the page source the time stamp in a slightly different, and portable international format (easily parsable). When the page is displayed, the new format is automatically converted to the current one ($TimeFmt), so the @@RecentChanges@@ pages will look exactly like before, but the source code will be slightly different. \\%0aIf you have custom $RecentChangesFmt settings, they will be preserved. If you have no custom settings but still prefer the old format, to revert to the old format, add this to @@config.php@@: %25hlt php%25[@%0a# revert to pre-2.3.0 RecentChanges%0a$RecentChangesFmt = array(%0a '$SiteGroup.AllRecentChanges' => %0a '* [[{$Group}.{$Name}]] . . . $CurrentTime $[by] $AuthorLink: [=$ChangeSummary=]',%0a '$Group.RecentChanges' =>%0a '* [[{$Group}/{$Name}]] . . . $CurrentTime $[by] $AuthorLink: [=$ChangeSummary=]');%0a@]%0a* The variable $EnableNotSavedWarning is now enabled by default. Add to @@config.php@@ $EnableNotSavedWarning = 0; to disable it. %0a* The core table of contents function ($PmTOC) has had its styles updated, in order to properly indent long sub-headings. Notably, the TOC links now have a @@display:block@@ setting and there are no line breaks between them. If you have previously added custom styles for PmTOC, please review these in case they need updating.%0a%0aSee also [[Release Notes]] for any changes between your previous version and the new one.%0a%0aIf you have any questions or difficulties, please let us know.%0a%0a%0a[[#v22v23]]%0a!! Upgrading from version 2.3.0 to more recent versions%0a%0a!!! [[ReleaseNotes#v2315|2.3.15]] GUI Edit Buttons change [[#guiedit]]%0a%0aPart of these functions were rewritten to avoid 'unsafe inline' JavaScript. While default and most custom buttons should work without change, you should no longer need to url-encode some characters like %25 or add backslashes. If you have such buttons, you may need to update their declarations to strip the extra backslashes. Please contact us if you need assistance.%0a%0a!!! [[ReleaseNotes#v2323|2.3.23]] PmToken [[#pmtoken]]%0a%0aThis version adds a session token to core edit, upload, attributes and other forms. This is a way to mitigate [[Wikipedia:CSRF|CSRF vulnerabilities]].%0a%0aAll core forms and elements have been updated and should work without change. %0a%0aSome installations might encounter the warning "Token invalid or missing" and the changes are not saved. This can be caused by custom edit or upload forms, automated scripts posting to the wiki, AJAX posting text or uploads used by some recipes, or partial upgrades where some core scripts haven't been updated. Most of these should be easy to update -- please check if you're using the latest recipe versions, or report such cases to us.%0a%0aTo update custom forms:%0a%0a* In a form written in wiki markup, include the element %25pmhlt%25[@(:input pmtoken:)@] after the [@(:input form...:)@] directive.%0a%0a* If your script defines the variable $PageUploadFmt, it should now include the element: %25hlt html%25@@[=%3cinput type='hidden' name='\$TokenName' value='\$TokenValue' />=]@@ inside the @@[=%3cform...>=]@@ element.%0a%0aIf you have customized @@$UnapprovedLinkFmt@@, you should update it to include the token argument @@$TokenName=$TokenValue@@ in the link URL, something like @@[=href='{\$PageUrl}?action=approvesites&\$TokenName=\$TokenValue'=]@@.%0a%0aIf you are unable to update your scripts, you can disable the PmToken functionality with this in config.php:%0a%0a%25hlt php%25[@%0a $EnablePmToken = 0; # edit, upload, attributes, approveurls%0a $PmFormEnablePmToken = 0; # PmForm%0a@]%0a%0aIf you have recipes or custom functions that make changes to the wiki, and you want to benefit from the built-in PmToken functions, see [[Functions#pmtoken]].%0a%0a!!! [[ReleaseNotes#v2331|2.3.31]] PrintFmt() [[#PrintFmt]]%0a%0aThe function PrintFmt() was refactored to process markup and wiki pages before outputting HTML headers, which would allow for markup in headers, footers, sidebars included from the skin, and action pages like the Auth form, to configure $HTMLHeaderFmt and $HTMLStylesFmt, and the directives %25pmhlt%25@@[=(:noheader:), (:notitle:), (:noleft:), (:noaction:)=]@@%25%25 to work from these pages. In case your wiki relied on the previous behavior, you can revert to it by adding to config.php:%0a%0a $EnablePrePrintFmt = 0;%0a%0aIf the new default mode is problematic on your wiki, please do let me know.%0a%0a%0a!!! [[ReleaseNotes#v2337|2.3.37]] [[Site.EditForm]], sortable, rowspan [[#v2337]]%0a%0a%25p pmhlt%25The page [[Site.EditForm]] has been modified, if you have customized it, you may want to edit this page and after [@(:input e_minorcheckbox:)@] remove the text "[@$[This is a minor edit]@]". This was needed to allow for the label to be automatically modified in some cases, notably when merging edits.%0a%0a$EnableSortable, and $EnableSimpleTableRowspan are now enabled by default. To disable them, set them to 0 in config.php.%0a%0a $EnableSortable = 0; # disable sortable tables%0a $EnableSimpleTableRowspan = 0; # disable rowspan in tables%0a%0a!! FAQ%0a>>faq%3c%3c [[#faq]]%0a%0aQ: How can I determine what version of PmWiki I'm running now?%0aA: See [[version]] - {Version$:Summary}.%0a%0aQ: How can I test a new version of PmWiki on my wiki without changing the prior version used by visitors?%0aA: The easy way to do this is to install the new version in a separate%0adirectory, and for the new version set (in @@local/config.php@@):%0a%25hlt php%25[@%0a $WikiLibDirs = array(&$WikiDir,%0a new PageStore('/path/to/existing/wiki.d/{$FullName}'),%0a new PageStore('wikilib.d/{$FullName}'));%0a%0a@]%0aThis lets you test the new version using existing page content%0awithout impacting the existing site or risking modification of%0athe pages. (Of course, any recipes or local customizations have to%0abe installed in the new version as well.) %0a%0aThen, once you're comfortable that the new version seems to work%0aas well as the old, it's safe to upgrade the old version (and one%0aknows of any configuration or page changes that need to be made).%0a
time=1724226144
|
