What should go in our NEWS file?

[Chris Marusich]

Hi Guix!

The Guix source tree contains a NEWS file in its root directory.  What
is supposed to go into this NEWS file?  When should we update it?

The GNU Standards just says that it should contain "a list of
user-visible changes worth mentioning" ((standards) NEWS File):

  6.7 The NEWS File
  =================

  In addition to its manual, the package should have a file named `NEWS'
  which contains a list of user-visible changes worth mentioning.  In
  each new release, add items to the front of the file and identify the
  version they pertain to.  Don't discard old items; leave them in the
  file after the newer items.  This way, a user upgrading from any
  previous version can see what is new.

     If the `NEWS' file gets very long, move some of the older items into
  a file named `ONEWS' and put a note at the end referring the user to
  that file.

I'm curious to know what sort of changes should be included in our NEWS
file, and what sort of changes should not.  I'd like to know so that I
will know when I need to update the file.

For example, here are some common changes that we make in Guix:

* Add a new package.
* Change a package.
* Add a new service type.
* Change a service type.
* Add a new Guix API or data type.
* Change a Guix API or data type.

And here are some things we do perhaps less frequently:

* Remove a package, service type, Guix API, or data type.
* Change something for security reasons.
* Change something in backwards incompatible ways.

I think it would be useful to put some guidelines for when to update the
NEWS file into the Contributing section of our manual.  However, I'm not
familiar with what we should put into the NEWS file, so I'm hoping that
others who have contributed more can offer insight on what to write.

-- 
Chris

signature.asc
Description: PGP signature