Split into sections

UPGRADING.md

@@ -7,9 +7,10 @@ This document aims to summarize all those  breaking changes and noteworthy thing
 that you might stumble across when upgrading from Phing 2 to 3.
 
 The list below is not exhaustive. We've tried to list all significant/breaking changes,
-but there's a chance we missed something. If that's the case,
-let us know!
+but there's a chance we missed something. If that's the case, let us know!
 
+General
+-------
 * Phing now requires at least PHP 7.4.
 * All Phing code is now namespaced. This means that existing references to classes
   that existed in earlier Phing versions will no longer work. For example, the
@@ -22,6 +23,9 @@ let us know!
 * Omitting the `basedir` property in the root `project` tag now means "." instead
   of the current working directory. This effectively reverts the change made in 
   http://www.phing.info/trac/ticket/309 ([dfdb0bc](https://github.com/phingofficial/phing/commit/dfdb0bc8095db18284de364b421d320be3c1b6fb))
+
+Tasks
+-----
 * The behavior of `MkdirTask` has changed to be same as of `mkdir` Linux command:
   * When using `MkdirTask` to create a nested directory including its parents
     (eg. `<mkdir dir="a/b/c" />`), the task now creates the parent directories
@@ -75,14 +79,35 @@ let us know!
   * Visualizer
   * ZendCodeAnalyser
   * ZendServerDevelopmentTools
+* Obsolete `ExportPropertiesTask` was removed in favor of the `EchoPropertiesTask`
+    ```xml
+    <exportproperties targetfile="output.props" />
+    <!-- is the same as -->
+    <echoproperties destfile="output.props" regex="/^((?!host\.)(?!os\.)(?!env\.)(?!phing\.)(?!php\.)(?!line\.)(?!user\.)[\s\S])*$/"/>
+    ```
+* `FileHashTask` creates now a file by default
+* Deprecated `scpsend` alias for the `ScpTask` was removed
+* Deprecated `command` attribute for the `ExecTask` was removed, in favor of the `executable` attribute and `arg` nested elements:
+    ```xml
+    <exec command="echo foo"/>
+    <!-- should become -->
+    <exec executable="/bin/echo">
+        <arg value="foo"/>
+    </exec>
+    ```
+* The `tstamp` task now supports ICU syntax
+* The `phpcpd` and `phploc` tasks are removed, because their upstream projects have been abandoned
 * The signature from `\Phing\Listener\DefaultLogger::formatTime` has been changed. Therefore, if you have written a
   logger that overrides this method, you will need to update its signature accordingly.
 * The way how Phing handles file sizes has been normalized, this is explained in documentation.
     * FileSizeTask: `unit` attribute can be an IEC or SI suffix.
     * HasFreeSpace condition: `needed` attribute can include an IEC or SI suffix.
     * Size selector: `units` attribute has been removed, `value` attribute can include an IEC or SI suffix.
     * TruncateTask: `length` attribute can include an IEC or SI suffix.
-* The way Phing handles and parses boolean values has changed significantly! In general, strings such as `true`, `false`, `TRUE`, `FALSE`, etc. 
+
+Properties
+----------
+* The way Phing handles and parses boolean values has changed significantly! In general, strings such as `true`, `false`, `TRUE`, `FALSE`, etc.
   are no longer parsed into their PHP native equivalent. Specifically:
   * The way how boolean values are handled inside tasks has been normalized. Therefore `t` is not a valid `true` value any longer.
     For a list of effected components follow https://github.com/phingofficial/phing/search?p=1&q=booleanValue
@@ -102,21 +127,3 @@ let us know!
     http.url = https://localhost:${http.port}
     ```
   In this case `http.url` expands to `https://localhost:80`,  _not_ `https://localhost:8080`.
-* Obsolete `ExportPropertiesTask` was removed in favor of the `EchoPropertiesTask`
-    ```xml
-    <exportproperties targetfile="output.props" />
-    <!-- is the same as -->
-    <echoproperties destfile="output.props" regex="/^((?!host\.)(?!os\.)(?!env\.)(?!phing\.)(?!php\.)(?!line\.)(?!user\.)[\s\S])*$/"/>
-    ```
-* `FileHashTask` creates now a file by default
-* Deprecated `scpsend` alias for the `ScpTask` was removed
-* Deprecated `command` attribute for the `ExecTask` was removed, in favor of the `executable` attribute and `arg` nested elements:
-    ```xml
-    <exec command="echo foo"/>
-    <!-- should become -->
-    <exec executable="/bin/echo">
-        <arg value="foo"/>
-    </exec>
-    ```
-* The `tstamp` task now supports ICU syntax 
-* The `phpcpd` and `phploc` tasks are removed, because their upstream projects have been abandoned