Re: [Nano-devel] have release changes in changelog.gz and NEWS.gz for incompatible changes or NEW far-reaching features/implicatons.

[shirish शिरीष]

at bottom:-

On 02/01/2017, Benno Schulenberg <address@hidden> wrote:
>
> Hello Shirish,

Hello Benno,

> On Sat, Dec 31, 2016, at 15:09, shirish शिरीष wrote:
>> Anyways, coming to the point, I have always had a fascination for how
>> projects evolve and what changes happened with a specific project. [...]
>>
>> changelog.gz - all changes, normal bug-fixes, smallish new features
>> are shared therein.
>
> Not quite.  In fact, /everything/ gets mentioned therein, /all/ changes
> -- that's why it's called a changelog, a log of changes.  The idea is
> that if some day a developer finds a problem with some function, he/she
> can search through the changelog to see which changes have been made to
> this function over time, and see if maybe one of those changes rings a
> bell, raises suspicion of possibly causing trouble.  Such a log file
> was essential in the times before version control systems.  But these
> days we have git.  The developer can just do 'git log -p somefile.c'
> and search for the function name.  They will not just get the commit
> message but also the exact code changes.  Or, if you know that some
> feature worked in an earlier version, there is 'git bisect': there is
> no need to laboriously interpret a changelog to figure out what change
> might have caused the problem -- 'git bisect' will find the precise
> commit that broke things within ten, fifteen minutes, half an hour,
> with just a bit of iteration.
>
>> NEWS.gz - This is red. It usually is one of the first things besides
>> looking at my config files to see what broke the package. Many a time
>> it has helped me trouble-shooting a problematic package.
>>
>> Now to my surprise, I saw that changelog.gz got stopped on 31st March
>> 2016 and NEWS.gz has all the rest from then onwards.
>
> The things that go into the NEWS file have not changed: for nano
> it has always been a record of the release announcements.
>
>> This in my limited knowledge and understanding makes it difficult to
>> troubleshoot the package, as I would have to parse/grep through it and
>> even then I would have to be lucky to know/get the right keywords in
>> order to see what the issue is.
>
> Of the last four versions of nano, what would you have liked to
> see in the NEWS file?  And all other things left unmentioned?
>
>> Could people revert to the old way of working, have changelog.gz have
>> all the changes and just have NEWS.gz to give news of incompatible
>> changes or a BIG change which may break the package in corner cases,
>> unexpected ways.
>
> As said above, the function of the NEWS file has not changed.
> It's just the Changelog that got discontinued when we moved to
> git.  Because git is all you need when you want to troubleshoot.
>
> Benno
>
> --
> http://www.fastmail.com - A fast, anti-spam email service.
>
>

While what you have shared is true and that works if you are using git
as you have shared, but when it gets packaged by Debian it isn't as
straightforward as that. And this will happen probably in other
distributions also

The maintainer will make his/her own notes and add that to changelog.Debian.gz

This is how the documentation part of nano's package looks -

address@hidden - [/usr/share/doc/nano] - [10043]
└─[$] ll -h

total 180K
drwxr-xr-x 2 root root 4.0K 2016-12-25 16:43 examples
-rw-r--r-- 1 root root  20K 2016-12-14 15:07 changelog.Debian.gz
-rw-r--r-- 1 root root 2.1K 2016-12-14 14:14 copyright
-rw-r--r-- 1 root root 3.2K 2016-12-12 19:38 IMPROVEMENTS.gz
-rw-r--r-- 1 root root  27K 2016-12-12 19:38 NEWS.gz
-rw-r--r-- 1 root root 2.4K 2016-12-09 14:52 AUTHORS
-rw-r--r-- 1 root root 2.4K 2016-11-22 19:31 README
-rw-r--r-- 1 root root  41K 2016-10-26 13:11 faq.html
-rw-r--r-- 1 root root 1.9K 2016-10-26 13:11 TODO.gz
-rw-r--r-- 1 root root 2.4K 2016-10-26 12:57 THANKS.gz
-rw-r--r-- 1 root root  59K 2016-06-26 23:11 changelog.gz

changelog.debian.gz is something that the Debian Developer/Maintainer
will share his/her notes about packaging etc.

address@hidden - [/usr/share/doc/nano] - [10044]
└─[$] zless changelog.Debian.gz

nano (2.7.2-1) unstable; urgency=medium

  * The """Alcaldesa de España""" release.
  * New upstream release.
  * Update Vcs-* fields following the migration to git.
  * Make Homepage field and nano-tiny manpages point to https.

 -- Jordi Mallach <address@hidden>  Wed, 14 Dec 2016 10:37:00 +0100

which is perfectly fine.

Simply put, if you are going to put everything in NEWS.gz then I would
suggest simply migrate everything from changelog.gz to NEWS.gz as
there is no purpose served by having a changelog which doesn't serve
any changes anymore.

My idea was simple  -

a. Have all changes and regressions reported in changelog.gz

b. Have all 'Major' 'interesting' and 'Breakability' changes shown in
NEWS.gz and not the rest -

See as an e.g. -

man-db 2.7.6 (11 December 2016)
===============================

Major changes since man-db 2.7.5:

        Fixes:
        ------

        o Fix build warnings with Perl 5.22.

        o Document that 'man -K' searches page source, not rendered text.

        o Fix a long-standing bug in man-db's internal cleanup stack
          mechanism: if a cleanup function was pushed unexpectedly between a
          push/pop pair, then popping the stack would remove the wrong
          cleanup function and chaos could ensue.  Avoid this by being more
          precise about which cleanup function should be popped.

        o SECURITY: Eliminate dangerous setgid-root directories.  In the
          default configuration, cache files and directories are now owned
          by man:man rather than man:root; man and mandb are now setgid man
          as well as setuid man (except in the --disable-setuid case).  This
          is a much simpler and safer solution to the original problem that
          caused my predecessor to make directories setgid root, and doesn't
          introduce any interesting new privilege since the man group's only
          real purpose is to be the man user's primary group and nothing in
          cache directories is group-writeable.

          Maintainers of distribution packagers should take care to review
          their installation rules in light of this change.

          As far as I know this has no CVE ID, but it is described here:

            
http://www.halfdog.net/Security/2015/SetgidDirectoryPrivilegeEscalation/

        o Fix manual page translation infrastructure to render tables
          correctly with po4a 0.47.

        Improvements:
        -------------

        o man now understands the <page>.<section> form on its command line,
          so for example 'man chmod.2' is now the same as 'man 2 chmod'.
          (Contributed by Mihail Konev.)

        o The owner of cache files is now configured separately from whether
          man and mandb are installed setuid, using the
          --enable-cache-owner[=USER] option.


So it does three things - it shares the most interesting bug fixes,
talks about possible security issue with what has been to
mitigate/minimize it and some improvements.

I would have to point out that this is Debian's own baby/project in
many ways (man-db) so that may not hold up .

My only intention is that NEWS.gz is not polluted with all and sundry
and only some specific changes which the developer feels is
signficant, for instance something like UTF-8 inclusion OR some sort
of fuzzing applied and whole lot of security issues taken care of or
something like that.

What is 'significant' and what is 'routine'  is left to the
developer/developers in question.

I hope have made it more clear. If however you want to use NEWS.gz to
continue to put all the changes in, then as shared before, just port
all the content from changes.gz to NEWS.gz and document this. It
doesn't make sense to have changelog in two different places.

Hope my argument is bit more understandable now.

-- 
          Regards,
          Shirish Agarwal  शिरीष अग्रवाल
  My quotes in this email licensed under CC 3.0
http://creativecommons.org/licenses/by-nc/3.0/
http://flossexperiences.wordpress.com
EB80 462B 08E1 A0DE A73A  2C2F 9F3D C7A4 E1C4 D2D8