Skip to content

Commit

Permalink
docs: make minor improvements to release note template (#328)
Browse files Browse the repository at this point in the history
- For notes, add text describing how present tense with "now" is permissible, and add
  examples that demonstrate it.
- Make it clearer that the items in the fixed issue list should be links.
  • Loading branch information
medubelko authored Jan 23, 2025
1 parent 9b08557 commit fbd7c43
Showing 1 changed file with 28 additions and 21 deletions.
49 changes: 28 additions & 21 deletions docs/release-notes/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
Release notes
=============

This page lists past release notes for Starcraft, summarising new features, bug
fixes and backwards-incompatible changes in each version. It also contains the
This page lists the notes for past releases of Starcraft, which summarise new features,
bug fixes and backwards-incompatible changes in each version. It also contains the
release and support policies for Starcraft.


Expand Down Expand Up @@ -141,15 +141,17 @@ development keeps pace with the OS's new releases and support lifecycle.>
them to provide users and authors an avenue for discoverability and
feedback.">
<Paragraph 2: Present the new behaviour or feature. In words, *show* what the
feature is and make a case for how the reader could benefit from it. Centre
the user whenever possible ("you"), and speak on behalf of Canonical ("we").
Prefer general, simple usage over complex applications. Use past tense. For
example, "We understand that some authors may not want to have their snaps
publicly ranked. If you prefer to disable ranking for your snap, we added the
``feedback`` key in Snapcraft recipes, which contains child keys for
controlling many of the rating and feedback features in the store. You can
declare ``voting: false`` to disable voting".>
<Paragraph 2: Present the new behaviour or feature. In words, *show* what the feature
is and make a case for how the reader could benefit from it. Centre the user whenever
possible ("you"), and speak on behalf of Canonical ("we"). Prefer general, simple
usage over complex applications. Use past tense, or the form "is now [x]" or "now
[does x]". For example, "We understand that some authors may not want to have their
snaps publicly ranked. If you prefer to disable ranking for your snap, we added the
``feedback`` key in Snapcraft recipes, which contains child keys for controlling many
of the rating and feedback features in the store. You can declare ``voting: false`` to
disable voting." Another example: "The Maven and Ant plugins now generate the more
standard path to the Java runtime executable instead of an unconventional one, making
their locations more predictable.">
<Paragraph 3, optional: Provide a call to action. This could take several
forms, such as a call to immediately perform a relevant action in Starcraft,
Expand All @@ -168,10 +170,12 @@ development keeps pace with the OS's new releases and support lifecycle.>
<Feature A>
~~~~~~~~~~~
<Add a short list of changes to the feature. Keep each item brief and for the
most part descriptive. There's little need to sell the change or give a
detailed reason. Use past tense. For example, "- Made the error message for
``method()`` more descriptive and recommend a likely remedy.">
<Add a short list of changes to the feature. Keep each item brief and for the most
part descriptive. There's little need to sell the change or give a detailed reason.
Use past tense, or the form "is now [x]" or "now [does x]". For example, "- Made the
error message for ``method()`` more descriptive and recommend a likely remedy."
Another example: "- The GET method on the profiles API now returns the user creation
date.">
Backwards-incompatible changes
Expand Down Expand Up @@ -230,7 +234,7 @@ development keeps pace with the OS's new releases and support lifecycle.>
<Feature D>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~
<Future deprecation: Use the same format as backwards-incompatible changes,
but use future tense to describe what we *intend* and *plan* to do in
Expand All @@ -255,17 +259,17 @@ development keeps pace with the OS's new releases and support lifecycle.>
See individual issue links for any mitigations.
- <Ticket ID> <Title>
- <Ticket ID> <Title>
- `ID <link>`_ <Title>
- `ID <link>`_ <Title>
Fixed bugs and issues
---------------------
The following issues have been resolved in Starcraft 2.0:
- <Ticket ID> <Title>
- <Ticket ID> <Title>
- `ID <link>`_ <Title>
- `ID <link>`_ <Title>
Contributors
Expand All @@ -274,4 +278,7 @@ development keeps pace with the OS's new releases and support lifecycle.>
We would like to express a big thank you to all the people who contributed to
this release.
`@alex <>`_, `@blair <>`_, `@cam <>`_, `@devin <>`_
:literalref:`@alex<https://example.com/alex>`,
:literalref:`@blair<https://example.com/blair>`,
:literalref:`@cam<https://example.com/cam>`,
and :literalref:`@devin<https://example.com/devin>`

0 comments on commit fbd7c43

Please sign in to comment.