Build RELEASE_NOTES.md from new-notes/ files

Adds new-notes files for the PRs already merged.
Future conflicts in the now-deleted RELEASE_NOTES.md file must be
turned into new-notes/PR-nnn.md files when resolving them.

documentation/Makefile

@@ -20,11 +20,23 @@ API_RST_FILES = $(addsuffix -api.rst, $(HEADER_TYPES))
 RTD_SRC = $(COMMON_DIR)/rtd-src
 
 DOCS += README.md
-DOCS += RELEASE_NOTES.md
 DOCS += ca-cli.md
 
+OLD_NOTES = $(wildcard ../RELEASE-*.md)
+DOCS += $(OLD_NOTES:../%=%)
+
+DOCS += RELEASE_NOTES.md
+NEW_DIR = ../new-notes
+NEW_NOTES = $(wildcard $(NEW_DIR)/*)
+
 include $(TOP)/configure/RULES
 
+MAKENOTES = ../make-notes.pl
+$(COMMON_DIR)/RELEASE_NOTES.md: $(NEW_NOTES) $(MAKENOTES)
+	@$(RM) $@
+	$(PERL) $(MAKENOTES) -o $@ $(EPICS_DEV_SNAPSHOT) \
+	    -V $(EPICS_SHORT_VERSION) -d $(abspath $(NEW_DIR))
+
 $(HEADER_MD_FILES): %_h.md: ../HEADER_h.md
 	$(EXPAND_TOOL) -t $(INSTALL_LOCATION) -DHEADER=$* $< $@
 

documentation/make-notes.pl

@@ -0,0 +1,91 @@
+#!/usr/bin/env perl
+#*************************************************************************
+# Copyright (c) 2025 UChicago Argonne LLC, as Operator of Argonne
+#     National Laboratory.
+# SPDX-License-Identifier: EPICS
+# EPICS BASE is distributed subject to a Software License Agreement found
+# in file LICENSE that is included with this distribution.
+#*************************************************************************
+
+# Tool to combine release note entries into a single markdown file.
+
+use strict;
+use warnings;
+
+use File::Basename;
+use Getopt::Std;
+
+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";
+    exit 2;
+}
+
+HELP_MESSAGE()
+    if !getopts('hd:o:D:V:') || $opt_h || @ARGV > 0;
+
+die "$tool: Directory from '-d' option doesn't exist\n"
+    unless -d $opt_d;
+
+open my $out, '>:encoding(UTF-8)', $opt_o or
+    die "$tool: Can't create $opt_o: $!\n";
+
+$SIG{__DIE__} = sub {
+    die @_ if $^S;  # Ignore eval deaths
+    close $out;
+    unlink $opt_o;
+};
+
+# Directory handle for scanning the new-notes directory
+opendir my $dh, $opt_d or
+    die "$tool: Can't open '-d' directory: $!\n";
+
+my @notes;
+foreach my $fn ( sort grep !/^\.\.?$/, readdir $dh ) {
+    next if $fn eq 'README.txt';
+    die "$tool: Not markdown? File '$fn' lacks '.md' extension\n"
+        unless $fn =~ m/\.md$/;
+    local $/;
+    my $file = "$opt_d/$fn";
+    push @notes, do {
+        open my $fh, '<:encoding(UTF-8)', $file or
+            die "$tool: Can't open file $file: $!\n";
+        <$fh>;
+    };
+}
+close $dh;
+
+print $out <<__REL_INTRO__;
+# Release Notes
+
+This document describes the changes that have been made 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.
+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.
+
+__REL_INTRO__
+
+print $out "## EPICS Release $opt_V\n\n";
+
+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.__
+
+## Changes merged since the last release
+
+__NEW_INTRO__
+
+print $out map { "$_\n" } @notes;
+
+close $out;
+

documentation/new-notes/PR-518.md

@@ -0,0 +1,7 @@
+### Reduce symbol and macro pollution from epicsAtomic.h on WIN32
+
+`epicsAtomic.h` no longer pulls in as many unneeded declarations and macros from
+`windows.h`. Prior to this change, including `epicsAtomic.h` at the wrong time
+could result in unexpected compiler errors. Due to the nature of `windows.h`,
+some unneeded declarations are still pulled in, however the number is greatly reduced.
+Code that needs these declarations should explicitly include `windows.h` before `epicsAtomic.h`.

documentation/new-notes/PR-592.md

@@ -0,0 +1,7 @@
+### New `dbServerStats()` API for iocStats
+
+A new routine provides the ability to request channel and client counts from
+named server layers that implement the `stats()` method, or to get a summary
+of the counts from all registered server layers. A preprocessor macro
+`HAS_DBSERVER_STATS` macro is defined in the `dbServer.h` header file to
+simplify code that needs to support older versions of Base as well.

documentation/new-notes/PR-599.md

@@ -0,0 +1,4 @@
+### epicsExport simplifications
+
+`epicsExportAddress()`, `epicsExportRegistrar()` and `epicsRegisterFunction()`
+no longer require to be wrapped in `extern "C" { }` in C++ code.

documentation/new-notes/PR-613.md

@@ -0,0 +1,4 @@
+### Enhancement to IOC `dbgrep` command
+
+`dbgrep` now takes an optional second string argument consisting of a list of field names
+separated by spaces, e.g. `dbgrep "*PRESSURE*", "VAL DESC"`

documentation/new-notes/PR-nnn.md

@@ -0,0 +1,17 @@
+### Conflict-free release note entries for GitHub pull requests
+
+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.
+
+In this new approach each pull request adds a separate Markdown file to the
+`documentation/new-notes` directory with a unique name. All these files get
+combined into a single `RELEASE-<version>.md` file when a release is made and
+the `new-notes` directory is emptied ready for further development.
+
+Instructions on creating new entries are provided in a `README.txt` file in
+the `documentation/new-notes` directory. Running `make` in the `documentation`
+directory will combine all the new entries into a `RELEASE_NOTES.md` file that
+then gets installed into the `doc` top-level directory. The `make` command
+will also install the older `RELEASE-<version>.md` files into that `doc`
+directory.

documentation/new-notes/README.txt

@@ -0,0 +1,46 @@
+documentation/new-notes/README.txt
+==================================
+
+The documentation/new-notes directory is for new release note entries that
+describe changes merged into EPICS Base since the previous release.
+Files here must be written in Markdown (see below) and have the extension
+'.md' at the end of their filename.
+No other files than this README.txt file are permitted 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 directory and concatenating the file
+contents in that order, separated by one extra newline character.
+
+The file gets a level-1 Markdown title added followed by an explanation,
+and 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.
+
+
+Writing a Release Notes entry
+-----------------------------
+
+Add a new file to the new-notes directory for your entry. If this is for a
+GitHub pull request to the epics-base project please use the name 'PR-nnn.md'
+where nnn is the number of the pull request. If you haven't created the pull
+request yet you can use the number from a related GitHub issue, or use another
+name and rename the file in the PR has been created.
+
+The file should start with a level-3 Markdown title for the entry, like this:
+
+    ### New way to add Release Notes
+
+The three '#' characters start in the left-most column.
+The title should provide a short summary, and not end in a period.
+A blank line must follow, then as many paragraphs of text and code-blocks
+as are needed to describe the change.
+
+Release note entries are not intended to provide full documentation of major
+features. For small features or changes though, they may provide all the
+information needed to understand and use the feature.