diff --git a/documentation/Makefile b/documentation/Makefile index 51c20110b..e1d3d74a7 100644 --- a/documentation/Makefile +++ b/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) diff --git a/documentation/make-notes.pl b/documentation/make-notes.pl index ed95521c4..051b9741a 100644 --- a/documentation/make-notes.pl +++ b/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-.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; diff --git a/documentation/new-notes/PR-628.md b/documentation/new-notes/PR-628.md index 15339faad..5b3d16556 100644 --- a/documentation/new-notes/PR-628.md +++ b/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-.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-.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-.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-.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-.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-.md` file is +described in the `documentation/ReleaseChecklist.html` file. diff --git a/documentation/new-notes/README.txt b/documentation/new-notes/README.txt index 0b565c3b8..1bb62b82d 100644 --- a/documentation/new-notes/README.txt +++ b/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-.md +files present in the documentation directory, sorted in version order with +the newest first. Writing a Release Notes entry