Add links to older release notes files, update wording

documentation/Makefile

@@ -21,13 +21,12 @@ RTD_SRC = $(COMMON_DIR)/rtd-src
 
 DOCS += README.md
 DOCS += ca-cli.md
+DOCS += RELEASE_NOTES.md
 
 OLD_NOTES = $(wildcard ../RELEASE-*.md)
 DOCS += $(OLD_NOTES:../%=%)
 
-ifneq ($(EPICS_DEV_SNAPSHOT),)
-    DOCS += RELEASE_NOTES.md
-else
+ifeq ($(EPICS_DEV_SNAPSHOT),)
     NOTES_DOC = ../RELEASE-$(EPICS_SHORT_VERSION).md
 endif
 
@@ -37,10 +36,10 @@ NEW_NOTES = $(wildcard $(NEW_DIR)/*.md)
 include $(TOP)/configure/RULES
 
 MAKENOTES = ../make-notes.pl
-$(COMMON_DIR)/RELEASE_NOTES.md: $(NEW_NOTES) $(MAKENOTES)
+$(COMMON_DIR)/RELEASE_NOTES.md: $(NEW_NOTES) $(NOTES_DOC) $(MAKENOTES)
 	@$(RM) $@
 	$(PERL) $(MAKENOTES) -o $@ -D -V $(EPICS_SHORT_VERSION) \
-	    -d $(abspath $(NEW_DIR))
+	    -d $(abspath $(NEW_DIR)) $(OLD_NOTES)
 
 ifdef NOTES_DOC
 $(NOTES_DOC): $(NEW_NOTES) $(MAKENOTES)

documentation/make-notes.pl

@@ -14,21 +14,25 @@ use warnings;
 
 use File::Basename;
 use Getopt::Std;
+use version;
 
 my $tool = basename($0);
 
 our ($opt_d, $opt_h, $opt_o, $opt_D, $opt_V);
 
 sub HELP_MESSAGE {
-    print STDERR "Usage: $tool -d new-notes -o outfile.md -D -V 7.0.10\n";
+    print STDERR "Usage: $tool -d new-notes -o outfile.md -D " .
+        "-V 7.0.10 RELEASE-7.0.9.md ...\n";
     exit 2;
 }
 
 HELP_MESSAGE()
-    if !getopts('hd:o:DV:') || $opt_h || @ARGV > 0;
+    if !getopts('hd:o:DV:') || $opt_h || (!$opt_D && @ARGV > 0);
 
 die "$tool: Directory from '-d' option doesn't exist\n"
     unless -d $opt_d;
+die "$tool: Output filename is '$opt_o' but must end with '.md'"
+    unless $opt_o =~ m/\.md$/;
 
 open my $out, '>:encoding(UTF-8)', $opt_o or
     die "$tool: Can't create $opt_o: $!\n";
@@ -61,34 +65,51 @@ foreach my $fn ( sort grep !/^\.\.?$/, readdir $dh ) {
 }
 close $dh;
 
-print $out <<__REL_INTRO__;
+sub relVers {
+    $_ = shift;
+    m/RELEASE-([0-9.]+)\.md/;
+    return $1;
+}
+
+# Reverse sort of the RELEASE-<version>.md filenames
+my @OLD_RELS = sort {
+    version->parse(relVers($b)) <=> version->parse(relVers($a));
+} @ARGV;
+
+print $out <<"__REL_INTRO__";
 # Release Notes
 
-This document describes the changes that have been made in this release of
+This document describes changes that have been included in this release of
 EPICS.
-Notes from earlier EPICS releases are now provided in a separate document for
-each version in the EPICS 7 series to date.
+Notes from earlier EPICS releases are now provided in separate documents for
+each version in the EPICS 7 series to date, linked below.
 Release documents are also included for the older Base 3.15 and 3.16 series.
 
-The external PVA submodules continue to have their own release notes files as
-before, but the entries describing changes in those submodules have been copied
-into the appropriate EPICS release files since version 7.0.5 and will be added
-in future releases.
+The external PVA submodules continue to maintain their own release notes files
+as before, but older entries describing changes in those submodules since
+version 7.0.5 have been copied into the appropriate release notes files linked
+below, and will be added to new EPICS Release Notes published in the future.
 
 __REL_INTRO__
 
-print $out "## EPICS Release $REL_VERS\n\n";
+print $out <<"__NEW_INTRO__" if $opt_D && scalar @notes;
+
+## EPICS Release $REL_VERS
 
-print $out <<__NEW_INTRO__ if $opt_D;
 __This version of EPICS has not been released yet.__
-__The version number shown above may be different to the version number
-that these changes eventually get released under.__
+__When the changes described below get released, the version number used may be
+different to the one given above.__
 
-## Changes merged since the last release
+The changes below have been merged into EPICS since the last published release.
 
 __NEW_INTRO__
 
-print $out map { "$_\n" } @notes;
+print $out map { "$_\n" } @notes, "-----\n\n";
+
+print $out map {
+    my $v = relVers($_);
+    "## [EPICS Release $v](RELEASE-$v.md)\n\n";
+} @OLD_RELS;
 
 close $out;
 

documentation/new-notes/PR-628.md

@@ -2,21 +2,28 @@
 
 GitHub [PR #628](https://github.com/epics-base/epics-base/pull/628)
 
-This release replaces the single `documentation/RELEASE_NOTES.md` file in the
-EPICS source tree with a mechanism that should prevent merge conflicts when new
-entries are added from multiple pull requests.
+This release replaces the developer-edited `documentation/RELEASE_NOTES.md`
+source file in the EPICS tree with a process that generates one file from
+individual files added for each changeset, thus preventing merge conflicts
+when new entries are added by multiple pull requests.
 
-In this new approach each pull request will add a separate Markdown file to the
-`documentation/new-notes` directory with a unique name.
-Instructions on creating new entries are provided in a `README.txt` file in the
-`documentation/new-notes` directory.
+For this new approach each pull request must add its own Markdown file to the
+`documentation/new-notes` directory, using a unique filename.
+When a release is made, all these files will be combined into a single
+`RELEASE-<version>.md` file and the `new-notes` directory emptied to prepare
+for development of the next release.
 
-All these files will be combined into a single `RELEASE-<version>.md` file when
-a release is made, and the `new-notes` directory emptied to prepare for
-development of the next release.
+The build process now descends into the `documentation` directory where the
+`RELEASE_NOTES.md` file is generated and installed into the `doc` top-level
+directory along with the `RELEASE-<version>.md` files documenting older EPICS
+releases going back to 3.15.
 
-Between releases, running `make` in the `documentation` directory will combine
-all the new entries into a single `RELEASE_NOTES.md` file that then gets
-installed into the `doc` top-level directory.
-That `make` command will also install the older `RELEASE-<version>.md` files
-into the `doc` directory.
+Between releases the generated `RELEASE_NOTES.md` file contains the text from
+any `new-notes` files added to document changes already merged.
+It also provides links to the older `RELEASE-<version>.md` files, so it remains
+the starting point for documentation on all release changes.
+
+Detailed instructions on creating new entries are provided in a `README.txt`
+file in the `documentation/new-notes` directory.
+The release-time process that generates a new `RELEASE-<version>.md` file is
+described in the `documentation/ReleaseChecklist.html` file.

documentation/new-notes/README.txt

@@ -11,16 +11,18 @@ This README.txt file is the only other file that should appear here.
 Generating RELEASE_NOTES.md
 ---------------------------
 
-Running 'make' inside the Base documentation directory will generate a
-file RELEASE_NOTES.md and install it into the top-level doc directory.
-The contents of the generated file are assembled by lexically sorting the
-filenames of the other files in this new-notes directory and concatenating
-the file contents in order, separated by an extra newline character.
+Running 'make' inside the Base documentation directory now generates a
+file RELEASE_NOTES.md and installs it into the top-level doc directory.
 
-The file gets a level-1 Markdown header and an explanation, followed by a
-level-2 header giving the Release version number. If the software is still
-a release snapshot, some extra lines are added explaining that before the
-concatenated note entries.
+The file starts with a level-1 Markdown header and some introductory text.
+If any new-notes files are present a level-2 header is added with a Release
+version number and a -DEV suffix, followed by some notes explaining their
+unreleased status. The new-notes filenames are lexically sorted and their
+contents added in order, separated by an extra newline character.
+
+Finally a series of links are added to all the older RELEASE-<version>.md
+files present in the documentation directory, sorted in version order with
+the newest first.
 
 
 Writing a Release Notes entry