From 7b010cecd8adc14bde582eacb5c0c911b9370b4a Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Fri, 18 Apr 2025 17:52:29 -0500 Subject: [PATCH] Update text --- documentation/new-notes/PR-628.md | 29 ++++++++++++++++----------- documentation/new-notes/README.txt | 32 +++++++++++++++++------------- 2 files changed, 35 insertions(+), 26 deletions(-) diff --git a/documentation/new-notes/PR-628.md b/documentation/new-notes/PR-628.md index dad06177f..15339faad 100644 --- a/documentation/new-notes/PR-628.md +++ b/documentation/new-notes/PR-628.md @@ -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-.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-.md` files into that `doc` -directory. +All these files will be combined into a single `RELEASE-.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-.md` files +into the `doc` directory. diff --git a/documentation/new-notes/README.txt b/documentation/new-notes/README.txt index 3f09e63b2..0b565c3b8 100644 --- a/documentation/new-notes/README.txt +++ b/documentation/new-notes/README.txt @@ -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