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 <[email protected]> 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 <[email protected]> wrote: > >> On Wed, Dec 17, 2014 at 3:09 PM, Mateusz Kowalczyk >> <[email protected]> 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 [email protected] >> >> <[email protected]> (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 <[email protected] >> > >> >> 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 <[email protected] >> > >> >>> 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 >> >>>> [email protected] >> >>>> http://lists.science.uu.nl/mailman/listinfo/nix-dev >> >>>> >> >>>> >> >> >> >> >> >> >> >> _______________________________________________ >> >> nix-dev mailing list >> >> [email protected] >> >> http://lists.science.uu.nl/mailman/listinfo/nix-dev >> >> >> > >> > >> > -- >> > Mateusz K. >> > _______________________________________________ >> > nix-dev mailing list >> > [email protected] >> > http://lists.science.uu.nl/mailman/listinfo/nix-dev >> _______________________________________________ >> nix-dev mailing list >> [email protected] >> http://lists.science.uu.nl/mailman/listinfo/nix-dev >> > > _______________________________________________ > nix-dev mailing list > [email protected] > http://lists.science.uu.nl/mailman/listinfo/nix-dev > >
_______________________________________________ nix-dev mailing list [email protected] http://lists.science.uu.nl/mailman/listinfo/nix-dev
