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

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

[Arnout Vandecappelle (Essensium/Mind)]

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>
---
v2: (after review by Yann)
- Run 'make graph-size' in the old environment, and save
  file-size-stats.csv instead of packages-file-list.txt.
- Run 'make clean' in the old environment.
- Split "Update Buildroot" as a separate, explicit step.
- Add a step to review the commit log for relevant packages.
- Drop review of the CHANGES file - the commit log is sufficient.
- Drop second patch ("individual packages") - the commit log is
  sufficient.
- Compare file-size-stats.csv after the build; also look for new files.
- Drop comparing defconfig - it's already covered by comparing
  file-size-stats.csv.
- Include Yann's experience in the commit message.
---
 docs/manual/migrating.txt | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/docs/manual/migrating.txt b/docs/manual/migrating.txt
index 92e487c71e..89860c0940 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.
+. 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
 
-- 
2.31.1

_______________________________________________
buildroot mailing list
buildroot@busybox.net
http://lists.busybox.net/mailman/listinfo/buildroot

Re: [Buildroot] [PATCH] docs/manual/migrating.txt: add section with general migrating tips

[Yann E. MORIN]

Arnout, All,

On 2021-08-03 17:44 +0200, Arnout Vandecappelle (Essensium/Mind) spake thusly:
> 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>

Applied to master, thanks.

Regards,
Yann E. MORIN.

> ---
> v2: (after review by Yann)
> - Run 'make graph-size' in the old environment, and save
>   file-size-stats.csv instead of packages-file-list.txt.
> - Run 'make clean' in the old environment.
> - Split "Update Buildroot" as a separate, explicit step.
> - Add a step to review the commit log for relevant packages.
> - Drop review of the CHANGES file - the commit log is sufficient.
> - Drop second patch ("individual packages") - the commit log is
>   sufficient.
> - Compare file-size-stats.csv after the build; also look for new files.
> - Drop comparing defconfig - it's already covered by comparing
>   file-size-stats.csv.
> - Include Yann's experience in the commit message.
> ---
>  docs/manual/migrating.txt | 30 ++++++++++++++++++++++++++++++
>  1 file changed, 30 insertions(+)
> 
> diff --git a/docs/manual/migrating.txt b/docs/manual/migrating.txt
> index 92e487c71e..89860c0940 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.
> +. 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
>  
> -- 
> 2.31.1
> 
> _______________________________________________
> buildroot mailing list
> buildroot@busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 561 099 427 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'
_______________________________________________
buildroot mailing list
buildroot@busybox.net
http://lists.busybox.net/mailman/listinfo/buildroot