epics/epics-base
0
0
Fork 0
Code Issues Pull Requests Projects Wiki Activity

Add links to older release notes files, update wording

Browse Source
This commit is contained in:
Andrew Johnson
2025-06-18 11:12:43 -05:00
parent 7b010cecd8
commit 91063e4caa
4 changed files with 74 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/new-notes/PR-628.md
+22 -15
View File
@@ -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 -9
View File
@@ -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