.changes madness with upstream updates

classic Classic list List threaded Threaded
19 messages Options
Reply | Threaded
Open this post in threaded view
|

.changes madness with upstream updates

Michael Ströder
HI!

Sometimes a submission of me gets declined because of changelog being
too short or too long referring to this policy:

https://en.opensuse.org/openSUSE:Creating_a_changes_file_%28RPM%29#What_goes_into_the_changelog

While the guide-lines were surely outlined with good aims I have to
question the current policy of package changelogs (*.changes) regarding
upstream updates. The rules are too blurry and boil down to "Do the
right thing".

I don't like to provide an extract of an upstream changelog because I'm
convinced that no packager is capable of extracting a really meaningful
essence from an upstream changelog. Furthermore I assume that upstream
developers are also lazy writing docs and the changelog would have been
already shorter if still meaningful.

So IMO the right way is to..

1. just mention upstream release and packaging changes

xor

2. add the complete changelog.

Ciao, Michael.


smime.p7s (5K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Aw: [opensuse-packaging] .changes madness with upstream updates

Axel Braun-2


> Gesendet: Montag, 16. Oktober 2017 um 11:10 Uhr
> Von: "Michael Ströder" <[hidden email]>
> An: opensuse-packaging <[hidden email]>
> Betreff: [opensuse-packaging] .changes madness with upstream updates
>
> HI!
>
> Sometimes a submission of me gets declined because of changelog being
> too short or too long referring to this policy:
>
> https://en.opensuse.org/openSUSE:Creating_a_changes_file_%28RPM%29#What_goes_into_the_changelog
>
> While the guide-lines were surely outlined with good aims I have to
> question the current policy of package changelogs (*.changes) regarding
> upstream updates. The rules are too blurry and boil down to "Do the
> right thing".
>
> I don't like to provide an extract of an upstream changelog because I'm
> convinced that no packager is capable of extracting a really meaningful
> essence from an upstream changelog. Furthermore I assume that upstream
> developers are also lazy writing docs and the changelog would have been
> already shorter if still meaningful.

*See Mercurial Change Log for Details*
is a common phrase I see in 'my' upstream packages. We had a lengthy discussion on this, and the developers are not willing to change this

> So IMO the right way is to..
>
> 1. just mention upstream release and packaging changes
>
> xor
>
> 2. add the complete changelog.

I vote for 1)!

Best
Axel
--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Aw: [opensuse-packaging] .changes madness with upstream updates

Bruno Friedmann-2
On lundi, 16 octobre 2017 11.19:30 h CEST Axel Braun wrote:

> > Gesendet: Montag, 16. Oktober 2017 um 11:10 Uhr
> > Von: "Michael Ströder" <[hidden email]>
> > An: opensuse-packaging <[hidden email]>
> > Betreff: [opensuse-packaging] .changes madness with upstream updates
> >
> > HI!
> >
> > Sometimes a submission of me gets declined because of changelog being
> > too short or too long referring to this policy:
> >
> > https://en.opensuse.org/openSUSE:Creating_a_changes_file_%28RPM%29#What_go
> > es_into_the_changelog
> >
> > While the guide-lines were surely outlined with good aims I have to
> > question the current policy of package changelogs (*.changes) regarding
> > upstream updates. The rules are too blurry and boil down to "Do the
> > right thing".
> >
> > I don't like to provide an extract of an upstream changelog because I'm
> > convinced that no packager is capable of extracting a really meaningful
> > essence from an upstream changelog. Furthermore I assume that upstream
> > developers are also lazy writing docs and the changelog would have been
> > already shorter if still meaningful.
>
> *See Mercurial Change Log for Details*
> is a common phrase I see in 'my' upstream packages. We had a lengthy
> discussion on this, and the developers are not willing to change this
> > So IMO the right way is to..
> >
> > 1. just mention upstream release and packaging changes
> >
> > xor
> >
> > 2. add the complete changelog.
>
> I vote for 1)!
>
> Best
> Axel

Also sometimes when possible get an upstream direct link
of those changes.

On my side, if I see something that has to be done by the users
I add it to the .changes :-)


--

Bruno Friedmann
 Ioda-Net Sàrl www.ioda-net.ch
 Bareos Partner, openSUSE Member, fsfe fellowship
 GPG KEY : D5C9B751C4653227
 irc: tigerfoot


--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: .changes madness with upstream updates

Richard Brown
In reply to this post by Michael Ströder
On 16 October 2017 at 11:10, Michael Ströder <[hidden email]> wrote:

> HI!
>
> Sometimes a submission of me gets declined because of changelog being
> too short or too long referring to this policy:
>
> https://en.opensuse.org/openSUSE:Creating_a_changes_file_%28RPM%29#What_goes_into_the_changelog
>
> While the guide-lines were surely outlined with good aims I have to
> question the current policy of package changelogs (*.changes) regarding
> upstream updates. The rules are too blurry and boil down to "Do the
> right thing".
>
> I don't like to provide an extract of an upstream changelog because I'm
> convinced that no packager is capable of extracting a really meaningful
> essence from an upstream changelog. Furthermore I assume that upstream
> developers are also lazy writing docs and the changelog would have been
> already shorter if still meaningful.
>
> So IMO the right way is to..
>
> 1. just mention upstream release and packaging changes
>
> xor
>
> 2. add the complete changelog.
>
> Ciao, Michael.

I disagree with 2. - a complete changelog is too much

My personal feeling is as follows:

- Minimal acceptable - just mention upstream release and packaging changes

- Ideal - upstream release, packaging changes and packagers
"highlights" of release if the package maintainer is confident they
have a meaningful understanding (I have more faith than you ;))

- Alternative - upstream release, packaging changes, and URL to full
release notes.

I personally consider my .changes entry to be 'too long' and start
feeling uncomfortable if its starting to exceed 5 lines of content,
and will absolutely force myself to refactor what I'm typing once I've
hit line 10
--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: .changes madness with upstream updates

Peter Czanik-2
Hi,

On 10/16/2017 02:11 PM, Richard Brown wrote:
> - Minimal acceptable - just mention upstream release and packaging
> changes
> - Ideal - upstream release, packaging changes and packagers
> "highlights" of release if the package maintainer is confident they
> have a meaningful understanding (I have more faith than you ;))
Depending on my time and mood I use one of these. Copy & paste of
upstream changelog makes no sense especially knowing that not all
upstream features can be packaged in openSUSE. For example in case of
syslog-ng, JAR files necessary to build Java-based destinations are
missing from openSUSE. So detailing Elasticsearch or Hadoop related
changes makes no sense at all.

Bye,
CzP

--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: .changes madness with upstream updates

Dominique Leuenberger / DimStar
On Mon, 2017-10-16 at 14:19 +0200, Peter Czanik wrote:

> Hi,
>
> On 10/16/2017 02:11 PM, Richard Brown wrote:
> > - Minimal acceptable - just mention upstream release and packaging
> > changes
> > - Ideal - upstream release, packaging changes and packagers
> > "highlights" of release if the package maintainer is confident they
> > have a meaningful understanding (I have more faith than you ;))
>
> Depending on my time and mood I use one of these. Copy & paste of
> upstream changelog makes no sense especially knowing that not all
> upstream features can be packaged in openSUSE. For example in case of
> syslog-ng, JAR files necessary to build Java-based destinations are
> missing from openSUSE. So detailing Elasticsearch or Hadoop related
> changes makes no sense at all.
This is actually what the guideline says you should be doing when using
upstream's changelog: strip irrelevant things (Windows installer fixes?
MacOSX build fix, non-openSUSE releated feature fixes).
 
So you do it all right - keep on doing it :) - But I agree: doing
serious packaging takes time and also some understanding (I keep on
telling people: don't just copy/paste the NEWS, but actually
READ/Understand it... not uncommonly you find out about new build deps
you might want to check, or even obsolete ones)

Cheers
Dominique

signature.asc (201 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: .changes madness with upstream updates

Marcus Rueckert-3
On 2017-10-16 12:56:24 +0000, Dominique Leuenberger / DimStar wrote:

> On Mon, 2017-10-16 at 14:19 +0200, Peter Czanik wrote:
> > Hi,
> >
> > On 10/16/2017 02:11 PM, Richard Brown wrote:
> > > - Minimal acceptable - just mention upstream release and packaging
> > > changes
> > > - Ideal - upstream release, packaging changes and packagers
> > > "highlights" of release if the package maintainer is confident they
> > > have a meaningful understanding (I have more faith than you ;))
> >
> > Depending on my time and mood I use one of these. Copy & paste of
> > upstream changelog makes no sense especially knowing that not all
> > upstream features can be packaged in openSUSE. For example in case of
> > syslog-ng, JAR files necessary to build Java-based destinations are
> > missing from openSUSE. So detailing Elasticsearch or Hadoop related
> > changes makes no sense at all.
>
> This is actually what the guideline says you should be doing when using
> upstream's changelog: strip irrelevant things (Windows installer fixes?
> MacOSX build fix, non-openSUSE releated feature fixes).
>  
> So you do it all right - keep on doing it :) - But I agree: doing
> serious packaging takes time and also some understanding (I keep on
> telling people: don't just copy/paste the NEWS, but actually
> READ/Understand it... not uncommonly you find out about new build deps
> you might want to check, or even obsolete ones)

TBH

the *understand* part is the important bit. if you submit something it
would be nice if you have at least some understand of the impact of your
submission.

   darix

--
           openSUSE - SUSE Linux is my linux
               openSUSE is good for you
                   www.opensuse.org
--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: .changes madness with upstream updates

Philipp Thomas
In reply to this post by Dominique Leuenberger / DimStar
* Dominique Leuenberger / DimStar ([hidden email]) [20171016 14:58]:

> This is actually what the guideline says you should be doing when using
> upstream's changelog: strip irrelevant things (Windows installer fixes?
> MacOSX build fix, non-openSUSE releated feature fixes).

And sometimes you're lucky to maintain a package like coreutils that has a
ChangeLog and NEWS that I often whish all other packages to have as every
addition, change in behaviour or bug fix is mentioned and in case of bugs
it's mentioned which release introduced that bug.

But I admit that it *is* sometimes hard to determine the importance of an
entry. My rule of thumb is if it's relevant for a user of the package, not
for someone that either wants to build his own packages or even change the
code.

Philipp
--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: .changes madness with upstream updates

Marcus Rueckert-3
On 2017-10-16 13:34:56 +0000, Philipp Thomas wrote:

> * Dominique Leuenberger / DimStar ([hidden email]) [20171016 14:58]:
>
> > This is actually what the guideline says you should be doing when using
> > upstream's changelog: strip irrelevant things (Windows installer fixes?
> > MacOSX build fix, non-openSUSE releated feature fixes).
>
> And sometimes you're lucky to maintain a package like coreutils that has a
> ChangeLog and NEWS that I often whish all other packages to have as every
> addition, change in behaviour or bug fix is mentioned and in case of bugs
> it's mentioned which release introduced that bug.
>
> But I admit that it *is* sometimes hard to determine the importance of an
> entry. My rule of thumb is if it's relevant for a user of the package, not
> for someone that either wants to build his own packages or even change the
> code.

Consider this: For all packages which do not have such a nice file, we
now suggest "I as a packager dont feel like doing the work, to compile
the list of important changes, instead i expect that every of other
contributors/users in the project goes through the hassle"

Seems much more reasonable no? One person doing the work vs dozens or
hundred of people having to do it over and over.

   darix

--
           openSUSE - SUSE Linux is my linux
               openSUSE is good for you
                   www.opensuse.org
--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: .changes madness with upstream updates

Michael Ströder
In reply to this post by Dominique Leuenberger / DimStar
Dominique Leuenberger / DimStar wrote:
> This is actually what the guideline says you should be doing when using
> upstream's changelog: strip irrelevant things (Windows installer fixes?
> MacOSX build fix, non-openSUSE releated feature fixes).

If two people are following same guidelines the result should be nearly
the same. IMO the current guidelines are not even close to that goal.

Ciao, Michael.


smime.p7s (5K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: .changes madness with upstream updates

Adam Majer
In reply to this post by Michael Ströder
On 10/16/2017 11:10 AM, Michael Ströder wrote:
> 1. just mention upstream release and packaging changes
>
> xor
>
> 2. add the complete changelog.

Sometimes the only change in version update is an entry in .changes file
and upstream tarball update. Sometimes it's a little more. But in both
cases the correct way to manage the .changes changelog is to put in
important changes for openSUSE users in there.

If you only mention packages changes and no upstream changes, then users
don't know what improvements happened, if any. Upstream changes could
include security fixes, CVE numbers and other things that are important
to track.

Ideally, the .changes files should capture all the important changes
upstream has done in the release. As to what is important, that's for
you to filter. *Read* upstream changelog and decide. But in every
release, try to find something in addition to "New upstream version
X.Y.Z" and include that in the .changes. If nothing else, it at least
makes your package look well maintained ;)

Cheers,
Adam
--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: .changes madness with upstream updates

Michael Ströder
Adam Majer wrote:

> On 10/16/2017 11:10 AM, Michael Ströder wrote:
>> 1. just mention upstream release and packaging changes
>>
>> xor
>>
>> 2. add the complete changelog.
>
> Sometimes the only change in version update is an entry in .changes file
> and upstream tarball update. Sometimes it's a little more. But in both
> cases the correct way to manage the .changes changelog is to put in
> important changes for openSUSE users in there.
>
> If you only mention packages changes and no upstream changes, then users
> don't know what improvements happened, if any. Upstream changes could
> include security fixes, CVE numbers and other things that are important
> to track.
>
> Ideally, the .changes files should capture all the important changes
> upstream has done in the release. As to what is important, that's for
> you to filter. *Read* upstream changelog and decide. But in every
> release, try to find something in addition to "New upstream version
> X.Y.Z" and include that in the .changes. If nothing else, it at least
> makes your package look well maintained ;)
Actually you're trying to explain the guidelines by mainly repeating
them. I appreciate you taking your time to do so.

IMHO I already carefully read the guide-lines and IMO I understood them
and also the good intentions behind them.

But I have some strong doubts. I even consider the guidelines to be harmful:

1. The guidelines are too blurry to let two packagers independently
produce similar results. Adding more rules to the guidelines won't help
and make things rather worse.

2. The guide lines encourage to add _incomplete_ information to
.changes. A "user" reading .changes won't be able to determine whether
there's enough information in there.
IMO it's much better to inform the user just about the upstream version
without any upstream changes information. This indicates that he has to
look somewhere else to get detailed information about causes of problems
he might run into.
Examples:
- sssd provides a section "Highlights" in its change log. Fine. I
usually simply copy&paste that to sssd.changes. But it's already quite
lengthy and it might not be important for a "user" trying to track down
issues in his *existing* deployment. This user needs information about
*all* changes.
- If e.g. a Python module like psutil announces specific changes for
non-Linux platforms this might cause a regression on Linux platforms.
Having the information about the change would possibly ring a bell.

3. Following your explanation above almost always will produce too many
lines added to .changes.

Therefore I consider the guidelines to be harmful, leading to false
information missing the goals.

So my suggestion is to just mention:
1. upstream release
2. packaging changes
3. security fixes / CVE numbers to make some automated compliance
checkers happy

Ciao, Michael.


smime.p7s (5K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: .changes madness with upstream updates

Adam Majer
On 11/08/2017 08:59 AM, Michael Ströder wrote:
> 1. The guidelines are too blurry to let two packagers independently
> produce similar results. Adding more rules to the guidelines won't help
> and make things rather worse.

That's on purpose. You are suppose to make a decision what is important
for users of your package, and what is not important. If two packagers
could independently create similar or the same results, then the process
could just be automated anyway.


> 2. The guide lines encourage to add _incomplete_ information to
> .changes. A "user" reading .changes won't be able to determine whether
> there's enough information in there.

The point of .changes is to list important changes for the users of your
package. It's subjective because it's meant to be fed into a human
brain, not into another computer ;)

Upstream changes could include things like "refactored module", but
that's probably not important to the users of the package. It doesn't
tell your users anything more than "new upstream version" anyway.


> IMO it's much better to inform the user just about the upstream version
> without any upstream changes information. This indicates that he has to
> look somewhere else to get detailed information about causes of problems
> he might run into.
> Examples:
> - sssd provides a section "Highlights" in its change log. Fine. I
> usually simply copy&paste that to sssd.changes. But it's already quite
> lengthy and it might not be important for a "user" trying to track down
> issues in his *existing* deployment. This user needs information about
> *all* changes.

If something is broken by upstream update, then the user should file a
bug report. I don't think we are expecting users to bisect upstream git
repositories so they can feed us patches?

As for "Highlights" section, I often do similar things for Boost or
NodeJS, but even then I cut it down to only include changes that are
important for openSUSE users, and I remove unrelated things like
upstream's acknowledgments or upstream bug reports or commits hashes.
Generally, you should not have more than 1 page of .changes describing
upstream version update. But having more than 1 line is generally very
desirable too.

So describe upstream changes in something between maybe 5 and 50 lines?
Like Executive Summary of business Financial Statements. Or like back of
the book summary for a novel. Just because space is at premium, don't
just throw up your hands and say "meh, can't list everything so let's
not bother".

> 3. Following your explanation above almost always will produce too many
> lines added to .changes.
>
> Therefore I consider the guidelines to be harmful, leading to false
> information missing the goals.
>
> So my suggestion is to just mention:
> 1. upstream release
> 2. packaging changes
> 3. security fixes / CVE numbers to make some automated compliance
> checkers happy

CVE numbers is not just to make compliance checkers happy. *Users* are
actually looking for these too!

- Adam
--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: .changes madness with upstream updates

Bernhard M. Wiedemann-5
In reply to this post by Marcus Rueckert-3
On 2017-10-16 15:44, Marcus Rueckert wrote:
> One person doing the work vs dozens or
> hundred of people having to do it over and over.

If upstreams would think about that, they could provide nicer summaries
of changes to save that effort for packagers in various distributions
(there are at least 13 distributions)
--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: .changes madness with upstream updates

Dave Plater lst


On 09/11/2017 11:24, Bernhard M. Wiedemann wrote:
> On 2017-10-16 15:44, Marcus Rueckert wrote:
>> One person doing the work vs dozens or
>> hundred of people having to do it over and over.
>
> If upstreams would think about that, they could provide nicer summaries
> of changes to save that effort for packagers in various distributions
> (there are at least 13 distributions)
>
+1 I have to extract changes from git logs for some packages.

Dave P
--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: .changes madness with upstream updates

Jan Engelhardt-4
On Thursday 2017-11-09 10:37, Dave Plater wrote:

>
>
> On 09/11/2017 11:24, Bernhard M. Wiedemann wrote:
>> On 2017-10-16 15:44, Marcus Rueckert wrote:
>>> One person doing the work vs dozens or
>>> hundred of people having to do it over and over.
>>
>> If upstreams would think about that, they could provide nicer summaries
>> of changes to save that effort for packagers in various distributions
>> (there are at least 13 distributions)
>>
> +1 I have to extract changes from git logs for some packages.

You don't _have_ to, though you can.

(So yeah, there is the emergency exit for mstroeder - always package git
snapshots and just say there was no info provided ;-)
--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: .changes madness with upstream updates

Michael Ströder
Jan Engelhardt wrote:
> (So yeah, there is the emergency exit for mstroeder - always package git
> snapshots and just say there was no info provided ;-)

My emergency exit is not to bother with packaging stuff for general use
at all. This also avoids the need to deal with your responses.

Ciao, Michael.


smime.p7s (5K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: .changes madness with upstream updates

Malcolm
In reply to this post by Bernhard M. Wiedemann-5
On Thu 09 Nov 2017 10:24:57 AM CST, Bernhard M. Wiedemann wrote:

>On 2017-10-16 15:44, Marcus Rueckert wrote:
>> One person doing the work vs dozens or
>> hundred of people having to do it over and over.  
>
>If upstreams would think about that, they could provide nicer summaries
>of changes to save that effort for packagers in various distributions
>(there are at least 13 distributions)
Hi
If the package has an appdata file, info can also be lurking here.....

For example with the bookworm package, working with upstream to see if
can add info on the pull/issue number etc so can update changes with
minimal fuss.

--
Cheers Malcolm °¿° SUSE Knowledge Partner (Linux Counter #276890)
openSUSE Leap 42.2 | GNOME 3.20.2 | 4.4.92-18.36-default
HP 255 G4 Notebook | A6-6310 X4 @ 1.80 GHz | AMD Radeon R4
up 1 day 17:30, 1 user, load average: 0.59, 0.95, 1.04


--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: .changes madness with upstream updates

Stefan Behlert
In reply to this post by Michael Ströder
Moin,

On Nov 08, 17 08:59:25 +0100, Michael Ströder wrote:
[....]

> Therefore I consider the guidelines to be harmful, leading to false
> information missing the goals.
>
> So my suggestion is to just mention:
> 1. upstream release
> 2. packaging changes
> 3. security fixes / CVE numbers to make some automated compliance
> checkers happy
>
> Ciao, Michael.
>

Well, I think there are advantages as wella s disadvantages in the way the
.changes are created, that's clear.
The bad thing is - those differe depending on which group of audience you
look into. And given that we ship the packages in various places and
distributions, it's no teven possible to say "that's the audience we want
it for". It's always a compromise - or the lesser evil.

I _personally_ hate the tendency of some upstream projects to not bobther
with changes any more, but just say "use gitlogs". But I am an
old-fashioned guy used to good .changes files from upstream :)

Businesswise, for the Enterprise releases, the changes-files are extremely
important, from a customer perspective as well as from a release manager
perspective. Not knowing all packages by heart, it's often the first source
of information "should/need we to take this?". And no, going  to the
webpages/gitlogs/otherstorage of upstream for each package is not want any
one would want...

A good changelog explains to me also, besides what you mentioned, changes
in behavior, incompatibilities, and gives me a rough outline why I would
want this.


        Stefan



--
Stefan Behlert, SUSE LINUX
Release Manager Enterprise Server
 
Maxfeldstr. 5, D-90409 Nuernberg, Germany
Phone +49-911-74053-173
SUSE Linux GmbH, GF: Felix Imendörffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nürnberg)
--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]