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

Adjust our release note and the new-notes/README file

Browse Source
This commit is contained in:
Andrew Johnson
2025-06-18 11:12:43 -05:00
parent e45da11703
commit 855696b4b1
2 changed files with 17 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/new-notes/PR-628.md
+10 -6
View File
@@ -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-<version>.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-<version>.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-<version>.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.
documentation/new-notes/README.txt
+7 -7
View File
@@ -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-<version>.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-<version>.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