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 ----------- ``` ### 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 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 known issues Known issues can be called out as follows: ```text The following known issues are present in this release and will be rectified in a future release: * xxx (#12345) ``` The editorial conventions for this block are similar to those for feature additions, except that an issue number is listed rather than a reference to a standard. #### 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 (CVE ID as link and any other relevant links) * Fixed (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]. ```