[Nix-dev] Breaking changes log

Wout Mertens wout.mertens at gmail.com
Thu Dec 18 17:18:08 CET 2014 

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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.science.uu.nl/pipermail/nix-dev/attachments/20141218/17b2d9a0/attachment-0001.html

More information about the nix-dev mailing list