What should go in our NEWS file?

What should go in our NEWS file?

[Chris Marusich]

[-- Attachment #1: Type: text/plain, Size: 1836 bytes --]

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

Re: What should go in our NEWS file?

[Ricardo Wurmus]

Hi Chris,

> 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?

It’s updated prior to making a release.

> 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.

As you can see we use the same sections for every new release:

   package management
   distribution (also includes list of package additions and updates)
   programming interfaces
   noteworthy bug fixes
   native language support

Some of these sections could be added to when a new notable feature has
been added (e.g. a new export format for “guix pack” or a new build
system).  In the past we have been doing this when preparing for the new
release, but it may make things easier on whoever cuts the new release
if we edited the file as needed when notable features are merged.

--
Ricardo

Re: What should go in our NEWS file?

[Ludovic Courtès]

Hello,

Ricardo Wurmus <rekado@elephly.net> skribis:

>> 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?
>
> It’s updated prior to making a release.

Committers following along should feel empowered to add noteworthy items
there, and not just right before the release.  This has to be rather
concise because there are so many things going on, and rather about
“important” changes, in the categories that Ricardo mentions.

I’m saying this because updating NEWS right before the release can be
quite cumbersome, and it’s also easy to overlook important things, so
any contribution in that regard can be very helpful!

Ludo’.

Re: What should go in our NEWS file?

[Ricardo Wurmus]

Ludovic Courtès <ludo@gnu.org> writes:

> Ricardo Wurmus <rekado@elephly.net> skribis:
>
>>> 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?
>>
>> It’s updated prior to making a release.
>
> Committers following along should feel empowered to add noteworthy items
> there, and not just right before the release.

Yes, absolutely!  It’s a hassle to go through all commits since the last
release and we have occasionally missed noteworthy changes.  We welcome
contributions to the NEWS file as noteworthy changes are made.

--
Ricardo