Christoph Biedl:
> Niels Thykier wrote...
>
>> I appreciate it was (hopefully) not your intention. But with that
>> remark you make me feel like I have wasted my time and effort trying to
>> the write the Jessie release notes.
>
> Niels,
>
> offending you was certainly the least of my interests. If I did, please
> accept my apologies.
>
>
> [...]
>
Thanks. As I suspected, it was unintended on your part.
>
> Still, the release notes leave me somewhat unsatisfied.
>
> [...]
>
> There was no input from my side. One reason was specific for jessie: It
> took me until June 2015 to get systemd running reliably. That was of
> course way too late to share experiences from the upgrades that
> followed.
>
For future reference, we updated the release-notes after the Jessie
release. Examples include:
*
https://www.debian.org/releases/jessie/amd64/release-notes/ch-information.en.html#systemd-sigkill-regression
- Discovered post Jessie and documented May 18th 2016.
- Updated again for 8.1
*
https://www.debian.org/releases/jessie/amd64/release-notes/ch-information.en.html#systemd-halt-behavior
- Added after 8.1 (Jun 2016)
*
https://www.debian.org/releases/jessie/amd64/release-notes/ch-information.en.html#squid-incompat
- Added after 8.1 (Sep 2016)
Of course, there is a diminishing "return on investment" for documenting
issues post the release, so please report them sooner rather than later.
(NB: If you noticed any of the Jessie issues that were fixed in a point
release, please let me know so we can add a "Fixed in 8.X" marker)
> Second is a problem of social interaction. If I notice an upgrade issue
> in a package, I'll have to deal with two parties instead of just one.
> Should I ask the maintainer to submit the text to you, or do this on my
> own at the risk this is considered hostile?
Marc Haber suggested we use a release-notes tag and I suspect this could
solve that issue.
> Also the release notes
> editors wish to be convinced, might deny the necessity, argue ... more
> time needed to write things down ...
With my Release note editor hat on - the major issues are:
* Learning of the issues to document
* Distil a 200-comment bug report into the 3 items:
- What changed/is broken?
- How to detect if a system is/will be affected?
- How to mitigate or fix the issue?
- E.g. if debconf is involved, how do we preseed the issue?
> there's so little incentive to
> contribute to the release notes, and passing the information but other
> means like blogs or (for the maintainer) NEWS.Debian avoids all the
> hazzle.[1]
>
From a personal PoV, I could be interested in decentralising this a bit
as well. Debian is still growing and eventually our current approach to
release notes will probably stop scaling.
I noticed there where some suggestions later in this mail (thread) for
doing something like that, which I will review later.
> The third reason is the question of how much in detail the release
> notes should actually be. In a strange way in the past they were too
> short. That made me reluctant to suggest entries for low-popcon
> packages as their significance doesn't match the prominence of being
> mentioned in the notes.
>
There is a certainly a trade-off here and I doubt we will ever be able
to come with a definition. Though a couple of guidelines:
* If it bricks the system (or otherwise makes the system unusable,
incl. unbootable), please report it.
* If it renders you unable to login (remotely), please report it.
* If it breaks running services, please report it.
As an example, we documented the removal of "whirlpool" support in
cryptsetup despite any default setup would never have had it:
*
https://www.debian.org/releases/jessie/amd64/release-notes/ch-information.en.html#cryptsetup-luks-whirlpool
> So for example, of the many other things that bit me in the jessie
> upgrade, the following two come to my mind:
>
> - rss2email changed the configuration and database file, and their
> location. A migration tool is provided (it caused grief, different
> story, mostly PEBKAC).
Given a notification about it, I might have added it to the
release-notes. Although, I cannot promise we will keep doing it for
packages with very low popcon ratings.
The major issue here being if the release-notes become too long they
will be unusable.
> - libnet-dns-perl had incompatible API changes, breaking applications.
(I presume it broke applications *not* packaged in Debian.)
In general, we cannot document every API change in a given release.
They would be far too many of those to keep track off and they would end
up flooding the release-notes. That said, we can certainly document
"selected" API breakages. E.g. Jessie included mentions for puppet and PHP.
https://www.debian.org/releases/jessie/amd64/release-notes/ch-information.en.html#puppet
https://www.debian.org/releases/jessie/amd64/release-notes/ch-information.en.html#php-incompat
>
> Or for the upcoming stretch release: Perl will, among other things, now
> check format strings at run time, whether the number of format
> specifiers matches the number of parameters, and create warnings
> otherwise.
>
I could be inclined to document that and other selected Perl changes.
Although, I am considering to group all the "language" changes as many
end-users will probably be unaffected these.
> Aside: Accidentially, two of these three are not administrative
> issues. Are the release notes restricted to that area by intention or
> did this just happen?
>
I suspect a bit of both. Also, I have biases in what I look for when I
scan for issues to document.
>>From past upgrades I estimate I could easily create 20 to 30 bits of
> that kind, and also that size. Do you consider such information
> relevant for the release notes? Then, given enough input, that document
> would become huge and rather a knowledge database. Probably nobody
> would read that completely.
It depends on the exact nature of the issue and the fix. That said, I
think decentralising it with some form of "subscription" might be a
better long term model (as you seem to suggest yourself in the next
paragraph).
> But wouldn't have to: Per package
> information, assessment ("you should know", "cosmetic issue", "manual
> intervention suggested", "will break your package", and a few more), a
> client using the list of packages actually installed - and I'd have a
> list of issues I should be prepared for on this very computer. That was
> nice to have.
>
Indeed.
> This raises the old question: What needs to be done people will share
> their upgrade experiences? A lot of knowledge is out there, it just
> doesn't hit the release notes.
>
Hmm, a couple of things I would like for such a system:
* It should be possible to add without updating a package
- Sadly we discover some issues to late and point releases can be
too long a delay
- This rules out apt-listchanges (as a completely solution unless
it got extended).
* Preferably, it would need translation support.
- NEWS items currently do not have this either.
* Bonus if we could add optional scriptable detection methods
- Implies a sandboxed DSL or signed scripts (with a trust model).
- The rationale being we had several items in the release notes where
a "simple" command could tell if your system was affected.
If people are interested in such a system, I am happy to help with it.
The less time people spend worrying about upgrading their systems, the
better we are doing! :)
> Regards
>
> Christoph
>
> [1] As an example for jessie:
>
> | Package: munin-node
> | Importance: should-know
> |
> | The ntp_* plugin now takes the ntp server address in numerical form
> | instead of hostnames. You will have to install libnet-dns-perl before
> | and re-run munin-node-configure after the upgrade. This will also
> | break historical data. If that's an issue rename the rrd files on the
> | server side accordingly, e.g. from
> | <host>-ntp_time_fu_berlin_de-offset-g.rrd to
> | <host>-ntp_130_133_1_10-offset-g.rrd
> [ aside: Will this worked for me, it might not be the best solution ]
>
> I can think of several ways getting flamed for this.
>
Attachment:
signature.asc
Description: OpenPGP digital signature