From a0fc67e0456e469b9fafe438f47de0b51c8c2963 Mon Sep 17 00:00:00 2001 From: Morgan Fainberg Date: Fri, 14 Dec 2018 07:20:44 -0800 Subject: [PATCH] Update template with guidance for bugs over bp Change the template and provide guidance for using a LP bug instead of the blueprints. This is due to the differences in blueprints and bugs. Blueprints do not have comments and the entire body is mutable. With the entire content being mutable (and having no real history functionality) anyone can change the blueprint and lose all tracking of patches proposed for the work. When a bug is used instead of a blueprint, each patch proposal and merge generates an immutable comment. Short of deleting the bug, the tracking of the work that has been done cannot be lost. Bugs can also be closed with a ``closes-bug`` line in the commit messages where specs take extra human intervention to mark as complete. Change-Id: Id575258f98baddc7e4fe1ebfe5c00e9ea3a87e9f --- specs/template.rst | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/specs/template.rst b/specs/template.rst index f56918d1..80f1118e 100644 --- a/specs/template.rst +++ b/specs/template.rst @@ -8,7 +8,7 @@ Example Spec - The title of your blueprint ========================================== -`bp example `_ +`bug #XXXXXXX `_ Introduction paragraph -- why are we doing anything? A single paragraph of @@ -21,9 +21,27 @@ Some notes about using this template: * Wrap text at 79 columns. -* The filename in the git repository should match the launchpad URL, for - example a URL of: https://blueprints.launchpad.net/keystone/+spec/new-feature - should be named new-feature.rst +* The filename in the git repository should be descriptive of the feature. + For example, if the feature is called "new feature", the file should be + named new-feature.rst + + Note that this process no longer uses the blueprints in launchpad and + instead uses a bug for tracking. Bugs are superior to blueprints in that + patches proposed and merged get a comment and comments on bugs are not + mutable. This ensures that the tracking of patches in our bug tracker + cannot be accidently lost if someone edits the body of the bug (unlike + blueprints, where all data is similar to the bug description and has + no history tracking. + +* You will need to open a bug in launchpad for tracking the changes. This + bug will be linked in the commit message of each patch for the feature + (including this specification) so that when a change is made the CI + system generate a comment on the bug and help us track all work being + done towards the feature. The bug number should replace the ``XXXXXXX`` + above in the link. + + Please be sure to use ``partial-bug: #XXXXXXX`` in the commit message + for landing this spec (where ``XXXXXXX`` is the bug id. * Do not delete any of the sections in this template. If you have nothing to say for a whole section, just write: None