[Buildroot] [git commit] docs/manual/migrating.txt: add section with general migrating tips

[Buildroot] [git commit] docs/manual/migrating.txt: add section with general migrating tips

[Yann E. MORIN]

commit: https://git.buildroot.net/buildroot/commit/?id=f24fb2382930f9bab25153085e69370e0a10d3bf
branch: https://git.buildroot.net/buildroot/commit/?id=refs/heads/master

This is based on Yann's and Arnout's experience with migrating
Buildroot.

Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
Cc: Yann E. MORIN <yann.morin.1998@free.fr>
[yann.morin.1998@free.fr: add "For more details, "]
Signed-off-by: Yann E. MORIN <yann.morin.1998@free.fr>
---
 docs/manual/migrating.txt | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/docs/manual/migrating.txt b/docs/manual/migrating.txt
index 92e487c71e..cb1f5eacc9 100644
--- a/docs/manual/migrating.txt
+++ b/docs/manual/migrating.txt
@@ -8,6 +8,36 @@ Some versions have introduced backward incompatibilities. This section
 explains those incompatibilities, and for each explains what to do to
 complete the migration.
 
+[[migrating-approach]]
+=== General approach
+
+To migrate from an older Buildroot version, take the following steps.
+
+. For all your configurations, do a build in the old Buildroot
+  environment. Run +make graph-size+. Save
+  +graphs/file-size-stats.csv+ in a different location. Run +make
+  clean+ to remove the rest.
+. Review the specific migration notes below and make the required
+  adaptations to external packages and custom build scripts.
+. Update Buildroot.
+. Run +make menuconfig+ starting from the existing +.config+.
+. If anything is enabled in the Legacy menu, check its help text,
+  unselect it, and save the configuration.
+. For more details, review the git commit messages for the packages that
+  you need. Change into the +packages+ directory and run
+  +git log <old version>.. -- <your packages>+.
+. Build in the new Buildroot environment.
+. Fix build issues in external packages (usually due to updated
+  dependencies).
+. Run +make graph-size+.
+. Compare the new +file-size-stats.csv+ with the original one, to
+  check if no required files have disappeared and if no new big unneeded
+  files have appeared.
+. For configuration (and other) files in a custom overlay that overwrite
+  files created by Buildroot, check if there are changes in the
+  Buildroot-generated file that need to be propagated to your custom
+  file.
+
 [[br2-external-converting]]
 === Migrating to 2016.11
 
_______________________________________________
buildroot mailing list
buildroot@busybox.net
http://lists.busybox.net/mailman/listinfo/buildroot