From 855696b4b15e481607163668979c7a0748da3107 Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Sun, 15 Jun 2025 23:57:19 -0500 Subject: [PATCH] Adjust our release note and the new-notes/README file --- documentation/new-notes/PR-628.md | 16 ++++++++++------ documentation/new-notes/README.txt | 14 +++++++------- 2 files changed, 17 insertions(+), 13 deletions(-) diff --git a/documentation/new-notes/PR-628.md b/documentation/new-notes/PR-628.md index 5b3d16556..8f2ae55eb 100644 --- a/documentation/new-notes/PR-628.md +++ b/documentation/new-notes/PR-628.md @@ -3,9 +3,10 @@ GitHub [PR #628](https://github.com/epics-base/epics-base/pull/628) 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. +source file in the EPICS tree with a process which generates that file from a +series of individual files added for each changeset in the release, thus +preventing merge conflicts when entries are added by many different pull +requests. For this new approach each pull request must add its own Markdown file to the `documentation/new-notes` directory, using a unique filename. @@ -13,10 +14,13 @@ 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. -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 +Developers can generate the `RELEASE_NOTES.md` file by running `make` in the +`documentation` directory, which will install the result in the `doc` top-level +directory along with the `RELEASE-.md` files describing older EPICS releases going back to 3.15. +The `documentation/Makefile` provides some other targets which can also be +requested, but they require additional non-EPICS software such as Doxygen and +Sphinx to have been installed first. Between releases the generated `RELEASE_NOTES.md` file contains the text from any `new-notes` files added to document changes already merged. diff --git a/documentation/new-notes/README.txt b/documentation/new-notes/README.txt index 1bb62b82d..e95f559af 100644 --- a/documentation/new-notes/README.txt +++ b/documentation/new-notes/README.txt @@ -20,9 +20,9 @@ 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. +Finally a series of myst Markdown directives are added which will include all +the older RELEASE-.md files present in the documentation directory +into the published HTML version, sorted in version order with the newest first. Writing a Release Notes entry @@ -42,10 +42,10 @@ The file should start with a level-3 Markdown title for the entry, like this: * The three '#' characters of the title start in the left-most column. * The title should provide a short summary, and not end in a period. - * The link to the GitHub pull-request should follow if appropriate, as its - own paragraph. - * A blank line must follow, then as many paragraphs of text and code-blocks - as are needed to describe the change, without going into too much detail. + * A link to the GitHub pull-request may follow if desired as shown above + (followed by a blank line to separate it from the next paragraph), or a + link to the PR may be integrated into the text that follows. + * Use blank lines between paragraphs of text, and code-blocks for examples. Release note entries are not intended to provide full documentation of major features. For small features or changes though, they may provide all the