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

[Julien Fischer]

On Tue, 20 Feb 2018, Zoltan Somogyi wrote:

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

I hadn't thought that far ahead :-)

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

So, something like

   # Changes to the Mercury standard library

   ## Changes to the array module
       .
       .
       .
   ## Changes to the char module
       .
       .
       .

etc etc?

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

One thing at a time (and if you think the NEWS file is a bit
of a mess you *really* don't want to look at the HISTORY file).

> 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 :-( ).

You're working on one of the things in that file right now!

Mind you, the contents of that file do seem to be a mixture of the
out-of-date, the trivial, the vague and absolutely gigantic pieces of
work.

>> (** 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" :-(

Yes, but as one of the likely culprits in the creation of said mess I
didn't want to press the point.

Julien.