diff --git a/doc/source/contributor/adding_release_notes.rst b/doc/source/contributor/adding_release_notes.rst new file mode 100644 index 000000000..e483a7766 --- /dev/null +++ b/doc/source/contributor/adding_release_notes.rst @@ -0,0 +1,160 @@ +.. _adding_release_notes: + +Release Notes +============= + +What are release notes? +~~~~~~~~~~~~~~~~~~~~~~~ + +Release notes are important for change management within manila. Since manila +follows a release cycle with milestones, release notes provide a way for the +community and users to quickly grasp what changes occurred within a development +milestone. To the OpenStack release management and documentation teams, +release notes are a way to compile changes per milestone. These notes are +published on the `OpenStack Releases website `_. +Automated tooling is built around ``releasenotes`` and they get appropriately +handled per release milestone, including any back-ports to stable releases. + +What needs a release note? +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Changes that impact an upgrade, most importantly, those that require a + deployer to take some action while upgrading + +* A new feature is implemented +* An existing feature is deprecated +* An existing feature is removed +* Behavior of an existing feature has changed in a discernible way to an end + user or administrator +* A security bug is fixed +* New configuration option is added + +What does not need a release note? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* A code change that doesn't change the general behavior of any + feature such as code refactor or logging changes. One case of this could be + the removal of the python 2.x compatibility layer, i.e., the "six" library + from code. +* Functional or unit test coverage enhancement +* Any change submitted with a justified TrivialFix flag added in the commit + message +* Adding or changing documentation within in-tree documentation guides + +How do I add a release note? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We use `Reno `_ to create and manage +release notes. The new subcommand combines a random suffix with a "slug" value +to make the new file with a unique name that is easy to identify again later. +To create a release note for your change, use: + +.. code-block:: console + + $ reno new slug-goes-here + +If reno is not installed globally on your system, you can use a tox +environment in manila: + +.. code-block:: console + + $ tox -e newnote -- slug-goes-here + +.. note:: + + When you are adding a bug-fix reno, name your file using the template: + "bug--slug-goes-here". + +Then add the notes in ``yaml`` format in the file created. Pay attention to the +type of section. The following are general sections to use: + +prelude + + General comments about the change. The prelude from all notes in a + release are combined, in note order, to produce a single prelude + introducing the release. + +features + + New features introduced + +issues + + A list of known issues with respect to the change being introduced. For + example, if the new feature in the change is experimental or known to not + work in some cases, it should be mentioned here. + +upgrade + + A list of upgrade notes in the release. Any removals that affect upgrades are + to be noted here. + +deprecations + + Any features, APIs, configuration options that the change has deprecated. + Deprecations are not removals. Deprecations suggest that there will be + support for a certain timeline. Deprecation should allow time for users + to make necessary changes for the removal to happen in a future release. + It is important to note the timeline of deprecation in this section. + +critical + + A list of *fixed* critical bugs (descriptions only). + +security + + A list of *fixed* security issues (descriptions only). + +fixes + + A list of other *fixed* bugs (descriptions only). + +other + + Other notes that are important but do not fall into any of the given + categories. + +:: + + --- + prelude: > + Replace this text with content to appear at the + top of the section for this change. + features: + - List new features here, or remove this section. + issues: + - List known issues here, or remove this section. + upgrade: + - List upgrade notes here, or remove this section. + deprecations: + - List deprecation notes here, or remove this section + critical: + - Add critical notes here, or remove this section. + security: + - Add security notes here, or remove this section. + fixes: + - Add normal bug fixes here, or remove this section. + other: + - Add other notes here, or remove this section. + + +Dos and Don'ts +~~~~~~~~~~~~~~ +* Release notes need to be succinct. Short and unambiguous descriptions are + preferred +* Write in past tense, unless you are writing an imperative statement +* Do not have blank sections in the file +* Do not include code or links +* Avoid special rst formatting unless absolutely necessary +* Always prefer including a release note in the same patch +* Release notes are not a replacement for developer/user/admin documentation +* Release notes are not a way of conveying behavior of any features or usage of + any APIs +* Limit a release note to fewer than 2-3 lines per change per section +* OpenStack prefers atomic changes. So remember that your change may need the + fewest sections possible +* General writing guidelines can be found + `here `_ +* Proofread your note. Pretend you are a user or a deployer who is reading + the note after a milestone or a release has been cut diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 2b6fd9439..6811d93e6 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -9,6 +9,13 @@ Basic Information contributing +Programming HowTos and Tutorials +-------------------------------- +.. toctree:: + :maxdepth: 3 + + adding_release_notes + Testing ------- diff --git a/tox.ini b/tox.ini index 23f157fd9..4d26cc2a5 100644 --- a/tox.ini +++ b/tox.ini @@ -24,6 +24,12 @@ commands = [testenv:debug] commands = oslo_debug_helper -t manilaclient/tests {posargs} +[testenv:newnote] +deps = + -c{env:TOX_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master} + -r{toxinidir}/doc/requirements.txt +commands = reno new {posargs} + [testenv:pep8] commands = flake8