[m-dev.] Renaming the NEWS file -> NEWS.md
jfischer at opturion.com
Wed Feb 21 00:01:04 AEDT 2018
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
>> 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
> - 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
>> (** 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.
More information about the developers