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

[Michael Nosthoff]

Hi,


On 03.08.21 17:19, Arnout Vandecappelle wrote:
>
> 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.

One thing I want to point out: The releases are tarballs. Should we 
assume the user has the git history available?


Regards,
Michael