Changes between Version 20 and Version 21 of 1.3/TracUpgrade

Timestamp:

Aug 29, 2017, 6:27:12 PM (7 years ago)

Author:

Ryan J Ollos

Comment:

Minor changes.

1.3/TracUpgrade

@@ -6 +6 @@
 == Instructions
 
-Typically, there are seven steps involved in upgrading to a newer version of Trac:
+There are seven recommended steps for upgrading to a newer version of Trac:
 
 === 1. Check your plugins
@@ -12 +12 @@
 Check whether your plugins are compatible with the version of Trac that you are upgrading to. Obsolete plugins listed in the [#VersionSpecificSteps version specific steps] below should be uninstalled or disabled.
 
-If you are upgrading to a minor release, plugin compatibility is usually not a concern because the Trac API typically does not change, and major features are not introduced, for minor releases.
+If you are upgrading to a minor release, plugin compatibility is usually not a concern because the Trac API rarely changes, and major features are usually not introduced, for minor releases.
 
 If your plugins are installed from [https://trac-hacks.org trac-hacks.org] you can check compatibility by looking for a tag on the project page corresponding to a major release (e.g. `1.2`). If you are unsure, you'll want to contact the plugin author or ask on the [trac:MailingList MailingList].
 
-If you are running several Trac plugins it is good to test the upgrade and site functionality in a staging instance of your site before upgrading your production instance. Remember, plugin authors are responsible for Trac version compatibility and plugins can interact in unexpected ways. Your Trac instance may have a unique combination of plugins and therefore it's a good idea to do some verification testing when making any changes to your site.
+If you are running several Trac plugins it is good to test the upgrade and plugin functionality in a staging instance of your site before upgrading your production instance. Remember, plugin authors are responsible for Trac version compatibility and plugins can interact in unexpected ways. Your Trac instance may have a unique combination of plugins and therefore it's advised that you do some verification testing when making any changes to your site.
 
 === 2. Bring your server off-line
@@ -40 +40 @@
 }}}
 
-You should also upgrade dependencies so they are compliant with the [TracInstall#Dependencies required versions] and upgrade Trac plugins.
+You should also upgrade dependencies so they are compliant with the [TracInstall#Dependencies required versions].
 
 === 4. Upgrade the Trac Environment #UpgradetheTracEnvironment
@@ -59 +59 @@
 === 5. Update the Trac Documentation === #UpdatetheTracDocumentation
 
-By default, every [TracEnvironment Trac environment] includes a copy of the Trac documentation for the installed version. However, to keep the included documentation in sync with the installed version of Trac, use the following [TracAdmin trac-admin] command to upgrade the documentation:
+By default, every [TracEnvironment Trac environment] includes a copy of the Trac documentation for the installed version. To keep the documentation in sync with the installed version of Trac, use the following [TracAdmin trac-admin] command to upgrade the documentation:
 {{{#!sh
 $ trac-admin /path/to/projenv wiki upgrade
@@ -73 +73 @@
 }}}
 
-Before refreshing, it is recommended that you remove the directory in which your static resources are deployed. The directory location depends on the choice you made during installation. This cleanup is not mandatory, but makes it easier to troubleshoot issues later on, as your installation is uncluttered by code or templates from a previous release that is not used anymore. As usual, make a backup before deleting the directory.
+Before refreshing, it is recommended that you remove the directory in which your static resources are deployed. The directory location depends on the choice you made during installation. This cleanup is not mandatory, but makes it easier to troubleshoot issues later on, as your installation is uncluttered by unused assets from a previous release. As usual, make a backup before deleting the directory.
 
 {{{#!div style="border: 1pt dotted; margin: 1em"
@@ -230 +230 @@
 === Customized Templates
 
-Trac supports customization of its templates by placing copies of the templates in the `<env>/templates` folder of your [TracEnvironment environment] or in a common location specified in the [[TracIni#GlobalConfiguration| [inherit] templates_dir]] configuration setting. If you choose to do so, be aware that you will need to repeat your changes manually on a copy of the new templates when you upgrade to a new release of Trac (even a minor one), as the templates will likely evolve. So keep a diff around.
+Trac supports customization of its templates by placing copies of the templates in the `<env>/templates` folder of your [TracEnvironment environment] or in a common location specified in the [[TracIni#GlobalConfiguration| [inherit] templates_dir]] configuration setting. If you choose to customize the templates, be aware that you will need to repeat your changes on a copy of the new templates when you upgrade to a new release of Trac (even a minor one), as the templates will evolve. So keep a diff around.
 
 The preferred way to perform TracInterfaceCustomization is a custom plugin doing client-side !JavaScript transformation of the generated output, as this is more robust in case of changes: we usually won't modify an element `id` or change its CSS `class`, and if we have to do so, this will be documented in the [trac:TracDev/ApiChanges] pages.
@@ -236 +236 @@
 === !ZipImportError
 
-Due to internal caching of zipped packages, whenever the content of the packages change on disk, the in-memory zip index will no longer match and you'll get irrecoverable !ZipImportError errors. Better anticipate and bring your server down for maintenance before upgrading.
+Due to internal caching of zipped packages, whenever the content of the packages change on disk, the in-memory zip index will no longer match and you'll get irrecoverable !ZipImportError errors. Better to anticipate and bring your server down for maintenance before upgrading.
 See [trac:#7014] for details.
 
@@ -255 +255 @@
 === Upgrading Python
 
-Upgrading Python to a newer version will require reinstallation of Python packages: Trac itself of course, but also [http://pypi.python.org/pypi/setuptools setuptools]. If you are using Subversion, you'll need to upgrade the [trac:TracSubversion Python bindings for SVN].
+Upgrading Python to a newer version will require reinstallation of Python packages: Trac itself of course, but also [TracInstall#Dependencies dependencies]. If you are using Subversion, you'll need to upgrade the [trac:TracSubversion Python bindings for SVN].
 
 === Changing Database Backend