[m-dev.] Renaming the NEWS file -> NEWS.md

Zoltan Somogyi zoltan.somogyi at runbox.com
Tue Feb 20 23:12:08 AEDT 2018



On Tue, 20 Feb 2018 05:15:20 -0500 (EST), Julien Fischer <jfischer at opturion.com> wrote:
> Since the Mercury repostitory is currently hosted on github, I have been
> considering renaming the NEWS file -> NEWS.md and tweaking the
> markdown** so that it is github flavoured.  Doing this means that when
> browsing the repository on github that the NEWS file would be nicely 
> formatted.
> 
> Are there any objections to doing this?

I don't object to using .md syntax, but how much "github flavouring"
are you intending to do?

Adding markdown to denote structure is probably best done *after*,
or *during*, fixing the structure, not before. The structure of the
current NEWS file leaves a lot to be desired. Here are some ideas
for improvements.

- The list of changes to library modules should have *exactly one*
  entry for any library module it mentions. Having more than one
  entry can be confusing for readers.

- Those entries should be sorted by module name. This should help us
   enforce the "only one mention" rule, and allows readers to find
   what they are interested in using binary search.

- Likewise, changes to compiler options should be described in
   exactly one entry (the usual change being the addition of the option),
   and the entries should be sorted by option name.

We should also consider having the NEWS.md file for a full release
include the changes since the previous full release, as now, but
moving those changes to the HISTORY file (HISTORY.md?)
immediately afterwards, so that between full releases (i.e. the vast
majority of the time), NEWS.md contains only the changes that
happened *since* the last full release.

We should probably delete the TODO file. We have not used it
in years (possibly decades :-( ).

> (** theoretically the NEWS file should already be markdown, but
> what some parts of it are in practice is anybody's guess.)

My guess is: "some parts are a mess" :-(

Zoltan.



More information about the developers mailing list