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

["Yann E. MORIN" <yann.morin.1998@free.fr>]

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.

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@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
> 

-- 
.-----------------.--------------------.------------------.--------------------.
|  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