[Nix-dev] Breaking changes log

Fri Dec 19 00:09:51 CET 2014

Great idea. A human readable changelog should mean less repetitive spam,
because people will know about breaking changes as they happen.

Aloha,
RK.

On Fri, Dec 19, 2014 at 2:18 AM, Wout Mertens <wout.mertens at gmail.com>
wrote:
>
> As a summary answer to all the answers, I think we should adopt a change
> log as described at http://keepachangelog.com/
>
> Why?
>
>    - It's an attempt at a standard with features that make it somewhat
>    machine-parseable (we could write a test for it)
>    - It's MarkDown format so human-readable and writeable, and github
>    formats it nicely. See
>    https://github.com/olivierlacan/keep-a-changelog/blob/gh-pages/CHANGELOG.md
>    for an example result.
>    - => Its diffs should also be human readable and a unified diff
>    between two versions gives you changes you care about. E.g.
>    https://github.com/olivierlacan/keep-a-changelog/commit/0417b6b4e824f459de3ad57c8ba7d4ea0967329c
>    - It's mostly insert-only so hopefully it won't result in PRs merge
>    conflicts and PRs can include their changes
>    - Very free-form so we can later add special tags that would allow
>    showing only messages relevant to the installed packages
>    - We would only need the one file, each branch has its own history and
>    CHANGELOG.md file
>    - See http://keepachangelog.com/ for a bunch of FAQs.
>
> Example (off the top of my head):
>
> # Change Log
> All notable changes to NixPkgs will be documented in this file.
>
> ## [Unstable][unstable]
> ### Changed
> - Bash completion is now on by default
> - [BREAKING] config.services.rsyncd exports attributes changed, now they share the same format as sambad
>
> ## [14.04] - 2014-04-30
> ### Security
> - Bash security fixes
> - OpenSSL Heartbleed fix
>
> [unstable]: https://github.com/NixOS/nixpkgs/compare/release-14.04...HEAD
> [14.04]: https://github.com/NixOS/nixpkgs/compare/release-13.10...release-14.04
>
>
> We probably don't want to include a line for each changed package, do we?
>
> Thoughts?
>
> Wout.
>
> PS: Hakisho, I top-post because Google makes me do it :)
>
> On Thu Dec 18 2014 at 11:29:04 AM Hakisho Nukama <nukama at gmail.com> wrote:
>
>> On Wed, Dec 17, 2014 at 3:09 PM, Mateusz Kowalczyk
>> <fuuzetsu at fuuzetsu.co.uk> wrote:
>> > On 12/17/2014 01:55 PM, Wout Mertens wrote:
>> >> Nice though it seems a bit complex. Not sure if it's over-engineered or
>> >> just what's needed.
>> >>
>> >> Also interesting:
>> >> *"There have been complaints regarding the comprehensibility of some
>> >> upgrade notices and news items in the past. This is understandable —
>> not
>> >> every Gentoo developer speaks English as a first language. However,
>> for the
>> >> sake of clarity, professionalism and avoiding making us look like
>> prats, it
>> >> is important that any language problems be corrected before inflicting
>> a
>> >> news item upon end users.*
>> >>
>> >> *Thus, at least 72 hours before a proposed news item is committed, it
>> must
>> >> be posted to the gentoo-dev mailing list and Cc:ed to pr at gentoo.org
>> >> <pr at gentoo.org> (exceptions may be made in exceptional
>> circumstances). Any
>> >> complaints — for example regarding wording, clarity or accuracy — must
>> be
>> >> addressed before the news item goes live."*
>> >>
>> >> <shudder>
>> >>
>> >> Wout.
>> >>
>> >
>> > This is just administrative mongering, no need to adopt it fully. I
>> > agree that either some kind of news system should be in place: currently
>> > I think the only thing we have going is putting ‘trace’ somewhere and
>> > hoping the user catches it.
>> >
>> > In any case, I think calling it ‘news’ is misled: in Gentoo news are
>> > used for longer term things, say distro moving off from Ruby 1.x for
>> > it's default or whatever. But maybe that's what OP wants.
>> >
>> > Personally I want to be able to emit a message from a package such as
>> > ‘XYZ flags have changed, you need to do such and such thing’ or ‘extra
>> > user interaction is needed to get this package to work, put this thing
>> > in such and such directory under $HOME’. Gentoo's portage does this,
>> > such things print during the package build (not always applicable) and
>> > at the end of the builds. I can see multiple problems here in that
>> > unlike with Gentoo, we often fetch multiple different versions of same
>> > software as various dependencies, the user is rarely directly using it
>> > all. I don't know how to deal with this properly. Maybe it's just a bad
>> > idea for nix.
>> >
>>
>> Maybe add all notable changes into a 'release-notes' [0]
>> for the unstable branch.
>> And merge unstable-entries that have not been nullified at release time
>> into the release-notes of the upcoming release.
>>
>> [0] https://github.com/NixOS/nixpkgs/blob/master/nixos/doc/
>> manual/release-notes/rl-unstable.xml
>>
>> Best Regards,
>> Hakisho Nukama
>>
>> P.S.: 'm not aware, if this is a top or bottom posting list, now I'm
>> in between. ;)
>>
>> >> On Wed Dec 17 2014 at 2:45:31 PM Oliver Charles <ollie at ocharles.org.uk
>> >
>> >> wrote:
>> >>
>> >>> One thing I really like is Gentoo's "news" feature - which seems to be
>> >>> discussed in detail at http://wiki.gentoo.org/wiki/GLEP:42. Maybe
>> >>> something like that is what you're envisioning?
>> >>>
>> >>> -- ocharles
>> >>>
>> >>> On Wed, Dec 17, 2014 at 1:27 PM, Wout Mertens <wout.mertens at gmail.com
>> >
>> >>> wrote:
>> >>>
>> >>>> Would it be nice if we kept a file with breaking changes?
>> >>>>
>> >>>> That way, nixos-rebuild should be able to list the breaking changes
>> >>>> between the current version of the channel and the last time the
>> system was
>> >>>> built.
>> >>>>
>> >>>> We'd also have the full list of breakage for release notes.
>> >>>>
>> >>>> Thoughts? What would such a log look like?
>> >>>>
>> >>>> Cheers,
>> >>>>
>> >>>> Wout.
>> >>>>
>> >>>> _______________________________________________
>> >>>> nix-dev mailing list
>> >>>> nix-dev at lists.science.uu.nl
>> >>>> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>> >>>>
>> >>>>
>> >>
>> >>
>> >>
>> >> _______________________________________________
>> >> nix-dev mailing list
>> >> nix-dev at lists.science.uu.nl
>> >> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>> >>
>> >
>> >
>> > --
>> > Mateusz K.
>> > _______________________________________________
>> > nix-dev mailing list
>> > nix-dev at lists.science.uu.nl
>> > http://lists.science.uu.nl/mailman/listinfo/nix-dev
>> _______________________________________________
>> nix-dev mailing list
>> nix-dev at lists.science.uu.nl
>> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>>
>
> _______________________________________________
> nix-dev mailing list
> nix-dev at lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.science.uu.nl/pipermail/nix-dev/attachments/20141219/20d15e93/attachment-0001.html 