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 <nuk...@gmail.com> wrote: > On Wed, Dec 17, 2014 at 3:09 PM, Mateusz Kowalczyk > <fuuze...@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 p...@gentoo.org > >> <p...@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 <ol...@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.mert...@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@lists.science.uu.nl > >>>> http://lists.science.uu.nl/mailman/listinfo/nix-dev > >>>> > >>>> > >> > >> > >> > >> _______________________________________________ > >> nix-dev mailing list > >> nix-dev@lists.science.uu.nl > >> http://lists.science.uu.nl/mailman/listinfo/nix-dev > >> > > > > > > -- > > Mateusz K. > > _______________________________________________ > > nix-dev mailing list > > nix-dev@lists.science.uu.nl > > http://lists.science.uu.nl/mailman/listinfo/nix-dev > _______________________________________________ > nix-dev mailing list > nix-dev@lists.science.uu.nl > http://lists.science.uu.nl/mailman/listinfo/nix-dev >
_______________________________________________ nix-dev mailing list nix-dev@lists.science.uu.nl http://lists.science.uu.nl/mailman/listinfo/nix-dev