Difference between revisions of "Blueprints"
m (Text replace - "__NOTOC__" to "") |
(New use for series goal, reformat tables for new wiki) |
||
| Line 1: | Line 1: | ||
| − | |||
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 | + | = Blueprints lifecycle = |
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. | 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. | ||
| Line 8: | Line 7: | ||
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. | 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. | ||
| − | Blueprints, like bugs, can be targeted towards | + | Blueprints, like bugs, can be targeted towards different milestones, so that at any point it's simple to see what the status of intended work is. |
| + | |||
| + | Here are the different steps in a blueprint's life: | ||
| + | |||
| + | === Creation === | ||
| + | |||
| + | If you intend to work on a given feature, you should create a blueprint for that. Adding a blueprint is simply a matter of going to the project's blueprints page, such as [1] and clicking on "Register a Blueprint". 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 optionally track the peer-review of your blueprint using the ''Drafter'' and ''Definition'' fields. | ||
| + | |||
| + | Once it is ready for PTL review, you should set: | ||
| + | |||
| + | * Milestone: Which part of the release cycle you think your work will be proposed for merging. | ||
| + | |||
| + | |||
| + | Click on ''Under development'' in [[Releases]] to access the current release cycle schedule. | ||
| + | |||
| + | === Inclusion in the release roadmap (PTLs) === | ||
| + | |||
| + | The PTL triages the blueprint by setting a priority: | ||
| + | |||
| + | * Priority: <blueprint priority> (see below) | ||
| + | |||
| − | + | He may also unset the target milestone and set the Definition to ''Obsolete'' (together with an explanation in the whiteboard) if the blueprint is a wrong idea altogether. | |
| − | === | + | === During development (assignee) === |
| − | + | The "Implementation" field should reflect progress in your work: | |
| − | + | * Implementation: <degree of completion> (see below) | |
| − | |||
| − | |||
| − | |||
| − | + | 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'' | |
| − | = | + | |
| + | = 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 use priority to communicate how important a given feature is to the success of the next release. | ||
| − | {| border="1 | + | {| border="1" |
| − | | | + | | ''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 | ||
|} | |} | ||
| − | === Implementation === | + | ==== Definition ==== |
| + | You can optionally use this field during the planning 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. | Use this status to indicate the degree of completion of your blueprint. This is mandatory. | ||
| − | {| border="1 | + | {| 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 | ||
|} | |} | ||
| − | |||
| − | {| border="1 | + | 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...) | + | 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. This is mandatory. | ||
| − | === 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. |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
= See also = | = See also = | ||
* [[ReleaseCycle]] | * [[ReleaseCycle]] | ||
* [[Bugs]] | * [[Bugs]] | ||
Revision as of 08:55, 10 July 2013
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 lifecycle
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.
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.
Blueprints, like bugs, can be targeted towards different milestones, so that at any point it's simple to see what the status of intended work is.
Here are the different steps in a blueprint's life:
Creation
If you intend to work on a given feature, you should create a blueprint for that. Adding a blueprint is simply a matter of going to the project's blueprints page, such as [1] and clicking on "Register a Blueprint". 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 optionally track the peer-review of your blueprint using the Drafter and Definition fields.
Once it is ready for PTL review, you should set:
- Milestone: Which part of the release cycle you think your work will be proposed for merging.
Click on Under development in Releases to access the current release cycle schedule.
Inclusion in the release roadmap (PTLs)
The PTL triages the blueprint by setting a priority:
- Priority: <blueprint priority> (see below)
He may also unset the target milestone and set the Definition to Obsolete (together with an explanation in the whiteboard) if the blueprint is a wrong idea altogether.
During development (assignee)
The "Implementation" field should reflect progress in your work:
- Implementation: <degree of completion> (see below)
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
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 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 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. This is mandatory.
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.
