[RFC,1/2] docs/manual/migrating.txt: add section with general migrating tips

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

Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
---
 docs/manual/migrating.txt | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

Arnout, All,

On 2021-08-02 18:22 +0200, Arnout Vandecappelle (Essensium/Mind) spake thusly:
> This is based on Arnout's experience with migrating Buildroot.

Except for the details, this also quite closely matches my own
experience.

> Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
> ---
>  docs/manual/migrating.txt | 28 ++++++++++++++++++++++++++++
>  1 file changed, 28 insertions(+)
> 
> diff --git a/docs/manual/migrating.txt b/docs/manual/migrating.txt
> index 92e487c71e..9fd7d7e676 100644
> --- a/docs/manual/migrating.txt
> +++ b/docs/manual/migrating.txt
> @@ -8,6 +8,34 @@ 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. Save the full +.config+ and
> +  +build/packages-file-list.txt+.

(read my comment below first, then come back here)
Maybe run 'make clean' here?

> +. Review the specific migration notes below and make the required
> +  adaptations to external packages and custom build scripts.
> +. In the new Buildroot environment, 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 CHANGES file to see if any of your packages and features
> +  are affected by the changes.
> +. Build in the new Buildroot environment.

Above, you said to start with a full build, so if folowing this sequence
to the letter, we still have a full build. We need to run 'make clean'
first (go back reading my comment, above).

> +. Fix build issues in external packages (usually due to updated
> +  dependencies).
> +. Compare the new +packages-file-list.txt+ with the original one, to
> +  check if no required files have disappeared.

Maybe also suggest graph-size et al. about investigating size changes,
too?

> +. 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.
> +. Run +make savedefconfig+ and verify that what is selected really is
> +  what you intended to enable.

I am always wary instructing people to look at defconfig files; I always
consider them to be artefacts of the configuration.

Rather, I suggest people read the output of legal-info to check that all
the packages there are acceptable, and see graph-depends to see how a
package came to the build.

Regards,
Yann E. MORIN.

>  [[br2-external-converting]]
>  === Migrating to 2016.11
>  
> -- 
> 2.31.1
>

On 02/08/2021 22:55, Yann E. MORIN wrote:
> Arnout, All,
> 
> On 2021-08-02 18:22 +0200, Arnout Vandecappelle (Essensium/Mind) spake thusly:
>> This is based on Arnout's experience with migrating Buildroot.
> 
> Except for the details, this also quite closely matches my own
> experience.

 Excellent. I'll remove the RFC bit from v2 then.

> 
>> Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
>> ---
>>  docs/manual/migrating.txt | 28 ++++++++++++++++++++++++++++
>>  1 file changed, 28 insertions(+)
>>
>> diff --git a/docs/manual/migrating.txt b/docs/manual/migrating.txt
>> index 92e487c71e..9fd7d7e676 100644
>> --- a/docs/manual/migrating.txt
>> +++ b/docs/manual/migrating.txt
>> @@ -8,6 +8,34 @@ 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. Save the full +.config+ and
>> +  +build/packages-file-list.txt+.
> 
> (read my comment below first, then come back here)
> Maybe run 'make clean' here?

 Mentally I assumed there would be an "old" buildroot directory with its output
directory, and a "new" buildroot directory with its distinct output directory.
But I indeed didn't write that, and in fact I don't work like that myself. So
'make clean' it is!


>> +. Review the specific migration notes below and make the required
>> +  adaptations to external packages and custom build scripts.
>> +. In the new Buildroot environment, 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 CHANGES file to see if any of your packages and features
>> +  are affected by the changes.
>> +. Build in the new Buildroot environment.
> 
> Above, you said to start with a full build, so if folowing this sequence
> to the letter, we still have a full build. We need to run 'make clean'
> first (go back reading my comment, above).
> 
>> +. Fix build issues in external packages (usually due to updated
>> +  dependencies).
>> +. Compare the new +packages-file-list.txt+ with the original one, to
>> +  check if no required files have disappeared.
> 
> Maybe also suggest graph-size et al. about investigating size changes,
> too?

 Excellent idea. You can easily compare the csv files.


>> +. 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.
>> +. Run +make savedefconfig+ and verify that what is selected really is
>> +  what you intended to enable.
> 
> I am always wary instructing people to look at defconfig files; I always
> consider them to be artefacts of the configuration.

 I agree with the principle. Unfortunately, I know of no better way of getting
the "top-level" packages.


> Rather, I suggest people read the output of legal-info to check that all
> the packages there are acceptable, and see graph-depends to see how a
> package came to the build.

 Theoretically, graph-depends gives the top-level packages as well (i.e. the
packages that ALL points to). However, for a reasonably-sized project with about
50 top-level packages, the graph is pretty much unreadable. 'grep -w _all
graphs/graph-depends.dot' is an alternative but it's not exactly user-friendly -
and it doesn't show the selected sub-options like the defconfig does.

 The defconfig isn't great either, of course. For example, it doesn't show the
sub-options that default y, and also choices aren't expressed very clearly.

 Actually, the main reason I use the defconfig is that it comes for free: 'make
savedefconfig; git diff'. So maybe I should mention that instead.

 Since this is a bit controversial, however, I'll just drop this point.


 Regarding legal-info: if it's just about getting a list of packages, graph-size
already gives that, so I think I will talk about graph-size but not about
legal-info.


 Regards,
 Arnout



> 
> Regards,
> Yann E. MORIN.
> 
>>  [[br2-external-converting]]
>>  === Migrating to 2016.11
>>  
>> -- 
>> 2.31.1
>>
>