diff options
author | Hugo Landau <hlandau@openssl.org> | 2023-11-20 14:54:10 +0000 |
---|---|---|
committer | Hugo Landau <hlandau@openssl.org> | 2023-11-29 08:35:28 +0000 |
commit | f90beba2510dd122174f100b21ddc75d621ebb48 (patch) | |
tree | 9b45723a02cbd3fae0197396044f722d3b131c93 | |
parent | a6e62c536537eb318fda9775da42ffb1febead38 (diff) |
Add proposed editorial conventions for NEWS.md
Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/22774)
(cherry picked from commit 036de8d4faceb0cef7b0730f0d0cb9ba9f85b497)
-rw-r--r-- | dev/NEWS-FORMAT.md | 193 |
1 files changed, 193 insertions, 0 deletions
diff --git a/dev/NEWS-FORMAT.md b/dev/NEWS-FORMAT.md new file mode 100644 index 0000000000..f856f78127 --- /dev/null +++ b/dev/NEWS-FORMAT.md @@ -0,0 +1,193 @@ +Editorial conventions for NEWS.md +================================= + +With 3.2 onwards we are seeking to make our NEWS.md file more like release +notes, structured to provide useful and pertinent information to those consuming +a release. + +General editorial principles +---------------------------- + +- Use `*` for top-level lists and use a blank line between each list item. + This makes the file more readable when read in raw form, which will commonly + occur when a user examines an unpacked tarball. + +- Cite RFCs with a space: `RFC 9000` + +- Put URLs at the end of the file and reference them rather than giving them + inline. This eases maintenance if a commonly used URL needs to be changed. + +- The blocks within a section for a release line are ordered roughly in + descending order of importance. Equally, list items within a block should be + listed in descending order of significance or severity. + +- Try to develop blog posts to match our wording, especially for the list of + new features. + +- Adopt uniform wording for lists where appropriate but do not insist on + sticking to them where these wordings are unworkable or suboptimal. + +- Everything here is a recommendation, not a requirement. + +- Omit blocks which have no items to list. + +Structure +--------- + +Each release line has a section, which is broken down into the initial and patch +releases within that release line. The most recent releases come first. + +The structure is as follows: + +```text +OpenSSL x.y +----------- + +<entry for patch releases of OpenSSL x.y...> +<entry for patch releases of OpenSSL x.y...> +<entry for initial (feature) release of OpenSSL x.y> +``` + +### Structure of a release entry + +For each release in a release line, the recommended structure is as follows: + +```text +### Major changes between OpenSSL {PREV_VERSION} and OpenSSL {VERSION} [1 Jan 2023] + +<opener paragraph> + +<one or more blocks listed below as applicable, in order shown below> + +<trailing advice> +``` + +#### Opener paragraph + +For a feature release, the following opener paragraph is suggested: + +```text +OpenSSL x.y.0 is a feature release adding significant new functionality to +OpenSSL. +``` + +For a patch release with no CVEs fixed, the following opener paragraph is +suggested: + +```text +OpenSSL x.y.z is a patch release. +``` + +For a patch release which fixes one or more CVEs, the following opener paragraph +is suggested, to be adjusted as appropriate: + +```text +OpenSSL x.y.z is a security patch release. The most severe CVE fixed in this +release is Medium. +``` + +#### Listing potentially incompatible changes + +If there are any potentially significant or incompatible changes, the following +block should be added: + +```text +This release incorporates the following potentially significant or incompatible +changes: + + * The ... has been changed so that xxx. + + * The ... has been changed so that yyy. + +``` + +Bullet items in this block should be complete sentences with trailing full stops +giving a brief summary. They may optionally be followed by full paragraphs +giving further information if needed. + +#### Listing feature additions + +If there are any feature additions, the following block should be added: + +```text +This release adds the following new features: + + * Support for ... (RFC 1234) + + * Support for ... (RFC 2345) + + This is an elaborating paragraph. + + * Multiple new features and improvements to ... + +``` + +Bullet items in this block should be summary lines without a trailing full stop +giving a brief summary, optionally followed by references to applicable +standards in parentheses. They may optionally be followed by full paragraphs +giving further information if needed. The summary line should not start with a +verb as the opener line for this block provides the verb. + +For consistency, use the wording `Support for ...` as the summary line if +possible and practical. + +List features in descending order of significance (approximately). + +#### Listing documentation enhancements + +Significant documentation enhancements can be called out as follows: + +```text +This release incorporates the following documentation enhancements: + + * Added xyz + + This is an elaborating paragraph, which might for example + provide a link to where this documentation can be viewed. + + * Clarified xyz + +``` + +The editorial conventions for this block are similar to those for feature +additions, except that the verb is part of the summary line. The other rules are +the same. + +For consistency, use the wording `Added ...` or `Clarified ...` as the summary +line if possible. + +#### Listing bug fixes and mitigations + +Significant bug fixes or mitigations can be called out as follows: + +```text +This release incorporates the following bug fixes and mitigations: + + * Mitigated <description of mitigation> (CVE ID as link and any other + relevant links) + + * Fixed <description of fix> (optional reference link or #issue number as + appropriate) +``` + +The words “bug fixes” or “mitigations” in the leader line should be deleted as +appropriate if inapplicable to a release. + +Fixes for issues with an issue number in the main repository should be given as +`#1234`. Any other issue (for example, a project issue) should be given as a +link, as most users will not know where to find such issues. + +List CVE mitigations first in descending order of severity, followed by bugs in +(very rough) descending order of severity. + +#### Trailing advice + +The following trailer is recommended: + +```text +A more detailed list of changes in this release can be found in the +[CHANGES.md] file. + +As always, bug reports and issues relating to OpenSSL can be [filed on our issue +tracker][issue tracker]. +``` |