Jump to: navigation, search

Difference between revisions of "Blueprints"

(→‎Adding a Blueprint)
(→‎See also)
 
(41 intermediate revisions by 11 users not shown)
Line 1: Line 1:
−
__NOTOC__
 
 
Launchpad blueprints are used to track the implementation of significant features in OpenStack. Keeping their status current is critical to the success of the release and the project as a whole. It avoids unnecessary reporting, pings and discussions, and keeps everyone on the same page.  
 
Launchpad blueprints are used to track the implementation of significant features in OpenStack. Keeping their status current is critical to the success of the release and the project as a whole. It avoids unnecessary reporting, pings and discussions, and keeps everyone on the same page.  
  
−
= Blueprints reference =
+
= Blueprints and Specs =
  
−
Blueprints offer a forum for listing and planning specifications for work to be done. Whereas one could think of these as bugs with a "Feature Request" priority, there is actually a more fundamental difference. A bug is a description of a problem, and a blueprint is a description of a solution. It would be perfectly legitimate, given the scope of a particular problem, to file a bug on a problem and then to write up a blueprint describing the approach to solving the problem. For most bugs this would be a rather large waste of time, but is merely pointed out to underscore the difference in purpose.
+
In addition to tracking implementation status, blueprints can also be used to propose a design and get it approved. Specifically, you can link to an external page that contains your specification, and use the "Design" fields in the blueprint to track the spec approval. However, Launchpad is missing a lot of features that would make iterating on spec design and approval usable, like ability to discuss or iterate on several revisions of a spec, or record multiple approvals.
  
−
The Blueprint system itself is quite simple, and the only thing required to create a blueprint is a title and a description of the blueprint. It is expected that longer-form official writeups of the approach would go on a wiki page, and accordingly the blueprint has a field for specifying where the writeup can be found. The intent here is that if you write a proper description of the work in the wiki, then once you are done with it you will be left with some form of documentation describing a particular feature.
+
In order to solve that issue, starting with the Juno cycle, some projects decided to experiment with using a specific git repository (*-specs) to propose, discuss, iterate and track approvals on specifications using Gerrit instead of Launchpad. Those projects still ultimately use Launchpad once the spec is approved, to track the implementation status of the approved feature.
  
−
Blueprints, like bugs, can be targeted towards different release series and different milestones, so that at any point it's simple to see what the status of intended work is.
+
That results in two slightly different workflows, depending on whether the targeted project uses a -specs repository or not.
  
−
Blueprints can also be used as the basis for planning in-person meetings. Launchpad contains a facility to register meetings, and blueprints can be targeted to available meetings as an element of agenda.
+
== Spec + Blueprints lifecycle ==
  
−
==== Adding a Blueprint ====
+
For projects using a -specs repository (like Nova, Neutron, Oslo, Ceilometer...), you should follow this process:
  
−
Adding a blueprint is simply a matter of going to the project's blueprints page, such as
+
* Register your blueprint in Launchpad by going to the project page at launchpad.net/$PROJECT and clicking "Register a blueprint"
 +
* Upload a design specification in the "specs/<release>" folder in $PROJECT-specs
 +
** e.g. http://git.openstack.org/cgit/openstack/nova-specs/tree/specs/juno/name-of-your-blueprint-in-launchpad
 +
** it should be based on the specs/template.rst, see the instructions in the template for more details
 +
** get it reviewed by submitting your patch using Gerrit, in the usual way: [http://docs.openstack.org/infra/manual/developers.html#development-workflow Development Workflow]
 +
** at the end of each release, non-completed specs will be removed
 +
** you need to re-submit for the following release, should the blueprint slip
 +
* Project drivers will approve blueprint by:
 +
** Setting priority
 +
** Setting a target milestone, based on the assignee proposal
 +
* Assignee then keeps milestone and implementation status current to reflect progress
 +
* Assignee sets implementation status to "Implemented" when the work is completed
  
−
<pre><nowiki>
 
−
https://blueprints.launchpad.net/nova
 
−
</nowiki></pre>
 
  
−
and clicking on "Register a Blueprint".
+
NB: an automated script will ensure that no milestone target is set on unapproved (unprioritized) blueprints.
  
−
==== Assigning a Blueprint ====
+
== Blueprints only lifecycle ==
  
−
Blueprints carry metadata about who wrote the spec, who approved the spec and who is implementing the spec. If there is a blueprint that you are going to be working on, simply change the assingee to yourself and off you go.
+
Projects not using a -specs repository (Horizon, Trove...), you should follow this process:
  
−
==== Updating Status ====
+
* Register your blueprint in Launchpad by going to the project page at launchpad.net/$PROJECT and clicking "Register a blueprint"
 +
** Describe the feature summarily in the blueprint itself
 +
** Link to another document (using the specification link) if you have more
 +
** Set yourself as assignee
 +
** Set target milestone to indicate when you expect the work to land
 +
* Project drivers will approve blueprint by:
 +
** Setting priority
 +
* Assignee then keeps milestone and implementation status current to reflect progress
 +
* Assignee sets implementation status to "Implemented" when the work is completed
  
−
Blueprints carry a status field about the relative status of the work. Although not strictly necessary, updating this status removes the need to constantly answer questions from your manager of "what's the status on project X"
 
  
−
== Available Fields in blueprints ==
+
= Blueprints reference =
  
 
Here are the different fields available in Launchpad blueprints, and how we use them within the OpenStack project.
 
Here are the different fields available in Launchpad blueprints, and how we use them within the OpenStack project.
  
−
=== Specification link ===
+
==== Specification link ====
 
URL to an additional document, potentially describing the design and implementation details.
 
URL to an additional document, potentially describing the design and implementation details.
  
−
=== Priority ===
+
==== Priority ====
  
−
PTLs use priority to communicate how important a given feature is to the success of the next release.
+
PTLs and their blueprint review teams use priority to communicate how important a given feature is to the success of the next release.
  
−
{| border="1" cellpadding="2" cellspacing="0"
+
{| border="1"
−
| ''Essential''  
+
| ''Essential''
 +
| Would prefer not to release without that feature
 +
|-
 +
| ''High''
 +
| Important feature that we should definitely have in the release
 +
|-
 +
| ''Medium''
 +
| Optional feature that should still be part of the roadmap
 
|-
 
|-
−
| ''High'', ''Medium'' and ''Low''
+
| ''Low''
 +
| Optional feature that may make it, but we should *not* follow on the release radar
 
|-
 
|-
−
| ''Undefined''  
+
| ''Undefined''
 +
| Blueprint has not been triaged yet
 
|}
 
|}
  
−
=== Definition ===
 
  
−
PTLs may ask you to use the definition status during the planning phase of the [[ReleaseCycle]].
+
==== Definition ====
 +
You can optionally use this field during the planning/approval phase. We also use it to mark a blueprint ''Superseded'' or ''Obsolete''.
  
−
{| border="1" cellpadding="2" cellspacing="0"
+
==== Implementation ====
−
|  ''New''
 
−
|-
 
−
|  ''Discussion''
 
−
|-
 
−
|  ''Drafting''
 
−
|-
 
−
|  ''Review''
 
−
|-
 
−
|  ''Pending approval''
 
−
|-
 
−
|  ''Approved''
 
−
|-
 
−
|  ''Superseded''
 
−
|-
 
−
|  ''Obsolete''
 
−
|}
 
−
 
 
−
=== Implementation ===
 
  
 
Use this status to indicate the degree of completion of your blueprint. This is mandatory.
 
Use this status to indicate the degree of completion of your blueprint. This is mandatory.
  
−
{| border="1" cellpadding="2" cellspacing="0"
+
{| border="1"
 
|  ''Unknown''  
 
|  ''Unknown''  
 +
| Implementation status was not set yet! Fix it!
 
|-
 
|-
 
|  ''Not started''  
 
|  ''Not started''  
 +
| Implementation is 0%
 
|-
 
|-
 
|  ''Started''  
 
|  ''Started''  
 +
| Implementation is > 0%
 
|-
 
|-
 
|  ''Blocked''  
 
|  ''Blocked''  
 +
| Implementation is blocked, see whiteboard for details, shall be discussed at next release meeting
 
|-
 
|-
 
|  ''Slow progress''  
 
|  ''Slow progress''  
 +
| Implementation is not blocked, but might miss the target milestone
 
|-
 
|-
 
|  ''Good progress''  
 
|  ''Good progress''  
 +
| Implementation is on track to be delivered at the targeted milestone
 
|-
 
|-
 
|  ''Beta available''  
 
|  ''Beta available''  
 +
| Implementation is almost complete, code is available in a branch or a draft review now
 
|-
 
|-
 
|  ''Needs code review''  
 
|  ''Needs code review''  
 +
| All changes were proposed in review
 
|-
 
|-
 
|  ''Implemented''  
 
|  ''Implemented''  
 +
| All changes were merged
 
|}
 
|}
  
−
Extra statuses:
 
  
−
{| border="1" cellpadding="2" cellspacing="0"
+
Extra statuses (you should probably not use them):
 +
 
 +
{| border="1"
 
|  ''Informational''  
 
|  ''Informational''  
 +
| No code changes needed. Maybe that didn't need a blueprint in the first place.
 
|-
 
|-
 
|  ''Deferred''  
 
|  ''Deferred''  
 +
| Blueprint was deferred to a future release. You should probably use the future series ''next'' milestone instead.
 
|-
 
|-
 
|  ''Needs infrastructure''  
 
|  ''Needs infrastructure''  
 +
| (not used)
 
|-
 
|-
 
|  ''Deployment''  
 
|  ''Deployment''  
 +
| (not used)
 
|}
 
|}
  
−
=== Series goal ===
+
==== Series goal ====
−
The release series (Essex, Folsom...) targeted by this blueprint. This is used by the PTL to build the roadmap for a given release.
+
The release series (Essex, Folsom...) for the proposed change. This should always match the target milestone. An automated script will ensure that the two fields match, it runs roughly every 2 hours.
  
−
=== Approver ===
+
==== Approver ====
−
The PTL for the project.
+
The PTL for the project (optional).
  
−
=== Drafter ===
+
==== Drafter ====
−
The person responsible for the planning phase on this blueprint.
+
The person responsible for the planning phase on this blueprint (optional).
  
−
=== Assignee ===
+
==== Assignee ====
 
The person responsible for implementing the blueprint. This is mandatory.
 
The person responsible for implementing the blueprint. This is mandatory.
  
−
=== Milestone target ===
+
==== Milestone target ====
−
The milestone the blueprint should be completed by. This is mandatory.
+
The milestone the blueprint should be completed by. Use of this field depends on the workflow followed (see above). In a spec-driven workflow, it's initially set by drivers at approval time. In a pure blueprint workflow, it's initially set by the assignee to communicate when the work is expected to land. In both cases, it's maintained by the assignee to communicate when the work is expected to land.
  
−
=== Related branches ===
+
==== Related branches ====
 
Not used.
 
Not used.
  
−
=== Related bugs ===
+
==== Related bugs ====
 
Bugs related to this blueprint, if any.
 
Bugs related to this blueprint, if any.
  
−
=== Sprints ===
+
==== Sprints ====
 
Not used.
 
Not used.
  
−
=== Feedback requests ===
+
==== Feedback requests ====
 
Not used.
 
Not used.
  
−
=== Whiteboard ===
+
==== Whiteboard ====
 
Free-form notes. If the blueprint implementation is blocked, this should state the reason why. Gerrit will add notes about corresponding reviews in this field.
 
Free-form notes. If the blueprint implementation is blocked, this should state the reason why. Gerrit will add notes about corresponding reviews in this field.
  
−
=== Dependency tree ===
+
==== Dependency tree ====
−
Dependencies between blueprints. If one blueprint needs to be delivered before this one, this needs to be recorded here.
+
Dependencies between blueprints. If one blueprint needs to be delivered before this one, this needs to be recorded here. Note that if B depends on A being completed, the priority of A should be as high (or higher) as the priority of B.
−
 
 
−
= Blueprints lifecycle =
 
−
 
 
−
=== Creation ===
 
−
 
 
−
If you intend to work on a given feature, you should create a blueprint for that. Describe the feature summarily in the blueprint itself, and link to another document (using the specification link) if you have more.
 
−
 
 
−
Note that you may track the peer-review of your blueprint using the ''Drafter'' and ''Definition'' fields.
 
−
 
 
−
Once it is ready for PTL review, you should set;
 
−
 
 
−
* Approver: <the PTL for the project>
 
−
* Assignee: <who will do the work>
 
−
* Series goal: Proposed for <the current development series>
 
−
* Milestone: When you think your work will be proposed for merging
 
−
 
 
−
=== Inclusion in the release roadmap (PTLs) ===
 
−
 
 
−
The PTL reviews the blueprint, then may include it as a release goal:
 
  
−
* Definition: ''Approved''
 
−
* Series goal: Accepted for <the current development series>
 
−
* Priority: <blueprint priority> (see above)
 
−
 
−
=== During development (assignee) ===
 
−
 
−
The "Implementation" field should reflect progress in your work:
 
−
 
−
* Implementation: <degree of completion> (see above)
 
−
 
−
Please update the implementation status regularly to avoid being pinged about it :)
 
−
 
−
=== When merged (assignee) ===
 
−
 
−
When the work is fully merged, finalize the spec by setting:
 
−
 
−
* Implementation: ''Implemented''
 
  
 
= See also =
 
= See also =
−
* [[ReleaseCycle]]
+
* http://docs.openstack.org/project-team-guide
 
* [[Bugs]]
 
* [[Bugs]]
 +
* https://blueprints.launchpad.net/openstack - the blueprints site
 +
 +
[[Category:Contribute]]

Latest revision as of 15:38, 13 June 2016

Launchpad blueprints are used to track the implementation of significant features in OpenStack. Keeping their status current is critical to the success of the release and the project as a whole. It avoids unnecessary reporting, pings and discussions, and keeps everyone on the same page.

Blueprints and Specs

In addition to tracking implementation status, blueprints can also be used to propose a design and get it approved. Specifically, you can link to an external page that contains your specification, and use the "Design" fields in the blueprint to track the spec approval. However, Launchpad is missing a lot of features that would make iterating on spec design and approval usable, like ability to discuss or iterate on several revisions of a spec, or record multiple approvals.

In order to solve that issue, starting with the Juno cycle, some projects decided to experiment with using a specific git repository (*-specs) to propose, discuss, iterate and track approvals on specifications using Gerrit instead of Launchpad. Those projects still ultimately use Launchpad once the spec is approved, to track the implementation status of the approved feature.

That results in two slightly different workflows, depending on whether the targeted project uses a -specs repository or not.

Spec + Blueprints lifecycle

For projects using a -specs repository (like Nova, Neutron, Oslo, Ceilometer...), you should follow this process:

  • Register your blueprint in Launchpad by going to the project page at launchpad.net/$PROJECT and clicking "Register a blueprint"
  • Upload a design specification in the "specs/<release>" folder in $PROJECT-specs
  • Project drivers will approve blueprint by:
    • Setting priority
    • Setting a target milestone, based on the assignee proposal
  • Assignee then keeps milestone and implementation status current to reflect progress
  • Assignee sets implementation status to "Implemented" when the work is completed


NB: an automated script will ensure that no milestone target is set on unapproved (unprioritized) blueprints.

Blueprints only lifecycle

Projects not using a -specs repository (Horizon, Trove...), you should follow this process:

  • Register your blueprint in Launchpad by going to the project page at launchpad.net/$PROJECT and clicking "Register a blueprint"
    • Describe the feature summarily in the blueprint itself
    • Link to another document (using the specification link) if you have more
    • Set yourself as assignee
    • Set target milestone to indicate when you expect the work to land
  • Project drivers will approve blueprint by:
    • Setting priority
  • Assignee then keeps milestone and implementation status current to reflect progress
  • Assignee sets implementation status to "Implemented" when the work is completed


Blueprints reference

Here are the different fields available in Launchpad blueprints, and how we use them within the OpenStack project.

Specification link

URL to an additional document, potentially describing the design and implementation details.

Priority

PTLs and their blueprint review teams use priority to communicate how important a given feature is to the success of the next release.

Essential Would prefer not to release without that feature
High Important feature that we should definitely have in the release
Medium Optional feature that should still be part of the roadmap
Low Optional feature that may make it, but we should *not* follow on the release radar
Undefined Blueprint has not been triaged yet


Definition

You can optionally use this field during the planning/approval phase. We also use it to mark a blueprint Superseded or Obsolete.

Implementation

Use this status to indicate the degree of completion of your blueprint. This is mandatory.

Unknown Implementation status was not set yet! Fix it!
Not started Implementation is 0%
Started Implementation is > 0%
Blocked Implementation is blocked, see whiteboard for details, shall be discussed at next release meeting
Slow progress Implementation is not blocked, but might miss the target milestone
Good progress Implementation is on track to be delivered at the targeted milestone
Beta available Implementation is almost complete, code is available in a branch or a draft review now
Needs code review All changes were proposed in review
Implemented All changes were merged


Extra statuses (you should probably not use them):

Informational No code changes needed. Maybe that didn't need a blueprint in the first place.
Deferred Blueprint was deferred to a future release. You should probably use the future series next milestone instead.
Needs infrastructure (not used)
Deployment (not used)

Series goal

The release series (Essex, Folsom...) for the proposed change. This should always match the target milestone. An automated script will ensure that the two fields match, it runs roughly every 2 hours.

Approver

The PTL for the project (optional).

Drafter

The person responsible for the planning phase on this blueprint (optional).

Assignee

The person responsible for implementing the blueprint. This is mandatory.

Milestone target

The milestone the blueprint should be completed by. Use of this field depends on the workflow followed (see above). In a spec-driven workflow, it's initially set by drivers at approval time. In a pure blueprint workflow, it's initially set by the assignee to communicate when the work is expected to land. In both cases, it's maintained by the assignee to communicate when the work is expected to land.

Related branches

Not used.

Related bugs

Bugs related to this blueprint, if any.

Sprints

Not used.

Feedback requests

Not used.

Whiteboard

Free-form notes. If the blueprint implementation is blocked, this should state the reason why. Gerrit will add notes about corresponding reviews in this field.

Dependency tree

Dependencies between blueprints. If one blueprint needs to be delivered before this one, this needs to be recorded here. Note that if B depends on A being completed, the priority of A should be as high (or higher) as the priority of B.


See also

Retrieved from "https://wiki.openstack.org/w/index.php?title=Blueprints&oldid=126646"