5.9 KiB

Raw Permalink Blame History

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:

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:

### 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:

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:

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:

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:

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:

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:

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:

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:

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:

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].

5.9 KiB Raw Permalink Blame History