| Message ID | 20210802162244.620782-2-arnout@mind.be |
|---|---|
| State | Changes Requested |
| Headers | show |
| Series | [RFC,1/2] docs/manual/migrating.txt: add section with general migrating tips | expand |
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 >
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@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 >> >
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
Micheal, All, On 2021-08-03 20:56 +0200, Michael Nosthoff spake thusly: > On 03.08.21 17:19, Arnout Vandecappelle wrote: > >On 03/08/2021 07:48, Yann E. MORIN wrote: > >>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. [--SNIP--] > >>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? People are really still using tarballs in these days? ;-) But OK, you've got a point. However, I would still think that people who want to follow a process when updating are probably already using buildroot a git submodule of some sorts, so yes, they will have a git tree to look at. People who use a released tarball are not really looking for a sustained or long-term vision, and are not planning on upgrading. So, I think we can state something like: - look at the CHANGES file, and run 'git log' on the packages of your interest; if you are not using git, clone the upstream repository for this. Regards, Yann E. MORIN.
Hello, On Tue, 3 Aug 2021 21:47:58 +0200 "Yann E. MORIN" <yann.morin.1998@free.fr> wrote: > People are really still using tarballs in these days? ;-) But OK, you've > got a point. > > However, I would still think that people who want to follow a process > when updating are probably already using buildroot a git submodule of > some sorts, so yes, they will have a git tree to look at. > > People who use a released tarball are not really looking for a sustained > or long-term vision, and are not planning on upgrading. I was also surprised, but the other day, a person working for a large IP vendor company complained that he was not able to download the Buildroot tarballs. For some reason, the IP of this company had been blocked in iptables rules of buildroot.org. When I suggested to use Git instead, and especially the Github or Gitlab mirrors as a workaround, it apparently wasn't considered really a good solution. So it does seem like some people are still using the tarballs, indeed. Thomas
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
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). 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(-)