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.
