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

Update text

Browse Source
This commit is contained in:
Andrew Johnson
2025-04-18 17:52:29 -05:00
parent 569e94b9fe
commit 7b010cecd8
2 changed files with 35 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
documentation/new-notes/PR-628.md
View File

@@ -1,17 +1,22 @@
### Conflict-free release note entries for GitHub pull requests
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.
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.
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.
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.
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.
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.

32
documentation/new-notes/README.txt
View File

@@ -5,7 +5,7 @@ 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.
This README.txt file is the only other file that should appear here.
Generating RELEASE_NOTES.md
@@ -14,13 +14,13 @@ 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.
filenames of the other files in this new-notes directory and concatenating
the file contents in order, separated by an 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.
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.
Writing a Release Notes entry
@@ -29,17 +29,21 @@ 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.
request yet you can use the number from a related GitHub issue, or use some
other name, then rename and push it after 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
### Conflict-free release note entries for GitHub pull requests
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.
GitHub [PR #628](https://github.com/epics-base/epics-base/pull/628)
* 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.
Release note entries are not intended to provide full documentation of major
features. For small features or changes though, they may provide all the