diff --git a/documentation/Makefile b/documentation/Makefile index c8c293d0e..b8b3c54eb 100644 --- a/documentation/Makefile +++ b/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=$* $< $@ diff --git a/documentation/make-notes.pl b/documentation/make-notes.pl new file mode 100644 index 000000000..0296821ba --- /dev/null +++ b/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; + diff --git a/documentation/new-notes/PR-518.md b/documentation/new-notes/PR-518.md new file mode 100644 index 000000000..ececf7cb0 --- /dev/null +++ b/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`. diff --git a/documentation/new-notes/PR-592.md b/documentation/new-notes/PR-592.md new file mode 100644 index 000000000..718fe1e77 --- /dev/null +++ b/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. diff --git a/documentation/new-notes/PR-599.md b/documentation/new-notes/PR-599.md new file mode 100644 index 000000000..91a67e683 --- /dev/null +++ b/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. diff --git a/documentation/new-notes/PR-613.md b/documentation/new-notes/PR-613.md new file mode 100644 index 000000000..74a7a0d0d --- /dev/null +++ b/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"` diff --git a/documentation/new-notes/PR-nnn.md b/documentation/new-notes/PR-nnn.md new file mode 100644 index 000000000..dad06177f --- /dev/null +++ b/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-.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-.md` files into that `doc` +directory. diff --git a/documentation/new-notes/README.txt b/documentation/new-notes/README.txt new file mode 100644 index 000000000..3f09e63b2 --- /dev/null +++ b/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.