[Buildroot] [RFC 2/2] docs/manual/migrating.txt: add "individual packages" section

[Arnout Vandecappelle]

On 03/08/2021 07:48, Yann E. MORIN wrote:
> Arnout, All,
> 
> On 2021-08-02 18:22 +0200, Arnout Vandecappelle (Essensium/Mind) spake thusly:
>> Add a section to the migrating documentation to explain what changed in
>> individual packages and how it may affect your build.
>>
>> This section is organised per package, not per Buildroot release,
>> because in general it's easier to check package per package if anything
>> changed than to check release per release for all your packages.
>>
>> The idea is that every time a package is changed in a way that is not
>> immediately obvious (mainly: affects runtime but not build time), it is
>> mentioned in this section. This may include:
>>
>> - a new version of the package got a new name due to API
>>   incompatibilities;
>> - the default behaviour or config optoins of the package changed;
>> - the Buildroot integration (e.g. configuration file, init script) of
>>   the package changed;
>> - what is installed by the package is changed (e.g. executable is
>>   renamed or removed).
> 
> No. Please, no.
> 
> We already have two locations were changes in packages are identified:
> 
>   - git commit logs, the authoritative reference,
> 
>   - the CHANGES files
> 
> I do not want to have to maintain yet a third, ever-growing and
> never-trimmed list. Also, we will always have to bikeshed whther such a
> change is disruptive enough or not to warrant being on that list...
> 
> Instead, I would just suggest that people run "git log --oneline" or
> "git log -p --stat" on the packages they are interested in.

 That's good advice as well. Simple "git log" should be sufficient though, if
the commit log is OK. "git log --oneline" is definitely not OK, because
important changes during a version bump will not appear in the oneline.

 I'm going to add a bullet point for this and merge it into the first patch.

 Regards,
 Arnout

> 
> And of course, that means we *need* well-written commit logs (but we're
> already pretty good I believe).
> 
> Having a section about the core internals, like the br2-defconfig stuff
> that is not obvious, or about the RPATH of host packages, is acceptable,
> because it is not easily discoverable.
> 
> Regards,
> Yann E. MORIN.
> 
>> To start with, add the recent changes of the installation defaults of
>> bluez5_utils.
>>
>> Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout at mind.be>
>> ---
>>  docs/manual/migrating.txt | 15 +++++++++++++--
>>  1 file changed, 13 insertions(+), 2 deletions(-)
>>
>> diff --git a/docs/manual/migrating.txt b/docs/manual/migrating.txt
>> index 9fd7d7e676..36e4aa4724 100644
>> --- a/docs/manual/migrating.txt
>> +++ b/docs/manual/migrating.txt
>> @@ -22,8 +22,8 @@ To migrate from an older Buildroot version, take the following steps.
>>    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.
>> +. Review the individual packages section below to see if any of your
>> +  packages are affected by the changes.
>>  . Build in the new Buildroot environment.
>>  . Fix build issues in external packages (usually due to updated
>>    dependencies).
>> @@ -36,6 +36,17 @@ To migrate from an older Buildroot version, take the following steps.
>>  . Run +make savedefconfig+ and verify that what is selected really is
>>    what you intended to enable.
>>  
>> +[[migrating-packages]]
>> +=== Individual packages
>> +
>> +This section describes changes to individual packages. For all packages
>> +that are built in your configuration, check below if changes are needed.
>> +
>> +==== bluez5_utils
>> +
>> +Since 2021.08, the tools and all plugins are optional and default off.
>> +Make sure to enable the plugins you require.
>> +
>>  [[br2-external-converting]]
>>  === Migrating to 2016.11
>>  
>> -- 
>> 2.31.1
>>
>