docs/manual: add appendix about migration from older versions

... and move the br2-external migration to it.

Reported-by: Adam Duskett <aduskett@gmail.com>
Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Adam Duskett <aduskett@gmail.com>
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>

diff --git a/docs/manual/appendix.txt b/docs/manual/appendix.txt
index 4d4bbecc183e84f0b543622a01c994e99283f56b..86afa4bdaa63e769f6c942a5ddcf909ed89b0e17 100644 (file)
--- a/docs/manual/appendix.txt
+++ b/docs/manual/appendix.txt
@@ -3,4 +3,4 @@
 
 include::makedev-syntax.txt[]
 include::makeusers-syntax.txt[]
-include::br2-external-converting.txt[]
+include::migrating.txt[]

diff --git a/docs/manual/br2-external-converting.txt b/docs/manual/br2-external-converting.txt
deleted file mode 100644 (file)
index 831addf..0000000
--- a/docs/manual/br2-external-converting.txt
+++ /dev/null
@@ -1,39 +0,0 @@
-// -*- mode:doc; -*-
-// vim: set syntax=asciidoc:
-
-[[br2-external-converting]]
-== Converting old br2-external trees
-
-Before Buildroot 2016.11, it was possible to use only one br2-external
-tree at once. With Buildroot 2016.11 came the possibility to use more
-than one simultaneously (for details, see xref:outside-br-custom[]).
-
-This however means that older br2-external trees are not usable as-is.
-A minor change has to be made: adding a name to your br2-external tree.
-
-This can be done very easily in just a few steps:
-
- * First, create a new file named +external.desc+, at the root of your
-   br2-external tree, with a single line defining the name of your
-   br2-external tree:
-+
-----
-$ echo 'name: NAME_OF_YOUR_TREE' >external.desc
-----
-+
-.Note
-Be careful when choosing a name: It has to be unique and be made
-with only ASCII characters from the set +[A-Za-z0-9_]+.
-
- * Then, change every occurence of +BR2_EXTERNAL+ in your br2-external
-   tree with the new variable:
-+
-----
-$ find . -type f | xargs sed -i 's/BR2_EXTERNAL/BR2_EXTERNAL_NAME_OF_YOUR_TREE_PATH/g'
-----
-
-Now, your br2-external tree can be used with Buildroot 2016.11 onward.
-
-.Note:
-This change makes your br2-external tree incompatible with Buildroot
-before 2016.11.

diff --git a/docs/manual/migrating.txt b/docs/manual/migrating.txt
new file mode 100644 (file)
index 0000000..24ea2e0
--- /dev/null
+++ b/docs/manual/migrating.txt
@@ -0,0 +1,46 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[migrating-from-ol-versions]]
+== Migrating from older Buildroot versions
+
+Some versions have introduced backward incompatibilities. This section
+explains those incompatibilities, and for each explains what to do to
+complete the migration.
+
+[[br2-external-converting]]
+=== Migrating to 2016.11
+
+Before Buildroot 2016.11, it was possible to use only one br2-external
+tree at once. With Buildroot 2016.11 came the possibility to use more
+than one simultaneously (for details, see xref:outside-br-custom[]).
+
+This however means that older br2-external trees are not usable as-is.
+A minor change has to be made: adding a name to your br2-external tree.
+
+This can be done very easily in just a few steps:
+
+ * First, create a new file named +external.desc+, at the root of your
+   br2-external tree, with a single line defining the name of your
+   br2-external tree:
++
+----
+$ echo 'name: NAME_OF_YOUR_TREE' >external.desc
+----
++
+.Note
+Be careful when choosing a name: It has to be unique and be made
+with only ASCII characters from the set +[A-Za-z0-9_]+.
+
+ * Then, change every occurence of +BR2_EXTERNAL+ in your br2-external
+   tree with the new variable:
++
+----
+$ find . -type f | xargs sed -i 's/BR2_EXTERNAL/BR2_EXTERNAL_NAME_OF_YOUR_TREE_PATH/g'
+----
+
+Now, your br2-external tree can be used with Buildroot 2016.11 onward.
+
+.Note:
+This change makes your br2-external tree incompatible with Buildroot
+before 2016.11.