Jump to: navigation, search

Blueprints

Revision as of 15:02, 25 May 2014 by Eglynn (talk | contribs) (Creation)

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.


For more information on the criteria used to review a blueprint, please see Blueprints#Blueprint_Review_Criteria. If your blueprint needs additional information, it will be put in the Review state. If approved, it will be marked as Approved and given a priority (initially Low).

Note that simply targeting a blueprint to a milestone is sufficient to get the blueprint in the queue to be reviewed. There is no need to email the mailing list or the PTL, or ping anyone on IRC.

Click on Under development in Releases to access the current release cycle schedule.

Nova

Nova has a team of people, led by the PTL, that are responsible for reviewing blueprints. That is the nova-drivers team.

To aid the reviewing of a blueprint by a team of people, the the design specifications related to each blueprint are reviewed in Gerrit, and stored in git, just like all the code: http://git.openstack.org/cgit/openstack/nova-specs

From Juno, the process for getting your blueprint Nova is:

  • Register your blueprint in launchpad (as normal)
  • Upload a design specification in the "specs/<release>" folder in nova-specs
  • Once your design specification has been committed to nova-specs:
    • Update your blueprint's specification URL to point to the design specification in nova-specs
    • Propose your blueprint, as above, by selecting the milestone in which you plan to complete the blueprint
  • nova-drivers will approve blueprint once:
    • proposer has picked a target milestone, URL points to nova-specs correctly, and code has been started
    • nova-drivers check there is code in gerrit, such that they think the proposed target is achievable
    • should blueprint slip to the next milestone, blueprint will be re-evaluated
  • Now everything continues as it would with any other OpenStack project

Neutron

The Neutron core developers review all BPs. Currently, the core team itself is responsible for this task. The process itself is very similar to the Nova process above:

To aid the reviewing of a blueprint by a team of people, the the design specifications related to each blueprint are reviewed in Gerrit, and stored in git, just like all the code: http://git.openstack.org/cgit/openstack/neutron-specs

From Juno, the process for getting your blueprint approved for Neutron is:

  • Register your blueprint in launchpad (as normal)
  • Upload a design specification in the "specs/<release>" folder in neutron-specs
  • Once your design specification has been committed to neutron-specs:
    • Update your blueprint's specification URL to point to the design specification in neutron-specs
    • Propose your blueprint, as above, by selecting the milestone in which you plan to complete the blueprint
  • Neutron cores will approve blueprint once:
    • proposer has picked a target milestone, URL points to neutron-specs correctly, and code has been started
    • Neutron cores will check there is code in gerrit, such that they think the proposed target is achievable
    • should blueprint slip to the next milestone, blueprint will be re-evaluated
  • Now everything continues as it would with any other OpenStack project

Oslo

The Oslo core team is responsible for reviewing blueprints.

To aid the reviewing of a blueprint by a team of people, the the design specifications related to each blueprint are reviewed in Gerrit, and stored in git, just like all the code: http://git.openstack.org/cgit/openstack/oslo-specs

From Juno, the process for getting your blueprint Oslo is:

  • Register your blueprint in launchpad (as normal)
  • Upload a design specification in the "specs/<release>" folder in oslo-specs
  • Once your design specification has been committed to oslo-specs:
    • Update your blueprint's specification URL to point to the design specification in oslo-specs
    • Propose your blueprint, as above, by selecting the milestone in which you plan to complete the blueprint
  • oslo-core will approve blueprint once:
    • proposer has picked a target milestone, URL points to oslo-specs correctly, and code has been started
    • oslo-drivers check there is code in gerrit, such that they think the proposed target is achievable
    • should blueprint slip to the next milestone, blueprint will be re-evaluated
  • Now everything continues as it would with any other OpenStack project

Ceilometer

The Ceilometer core team is responsible for reviewing blueprints.

The process is currently identical to that described above for Olso, Neutron & Nova, with the substitution of “ceilometer” for the corresponding project name in the text.

So, rather than copy & paste that boilerplate, instead we could take a moment to consider the ideal culture that should be adhered to for specs, as opposed code, reviews. In particular, please refrain from nitpicking on spelling or grammar, unless the meaning really is in danger of being obscured; a spelling nit may be noted, but with a clear indication that this is non-blocking feedback and only needs to be addressed if the proposer happens to be pushing a new patchset anyway. Also, bikeshedding is to be avoided. Instead please concentrate on constructively critquing the core concepts and design ideas for completeness, correctness, performance, maintainability, usability, and fidelity to the ceilometer project mandate.

Inclusion in the release roadmap (PTLs)

The PTL, possibly with the help of a blueprint review team, triages the blueprint by setting a priority:

  • Priority: <blueprint priority> (see below)


They 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 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


Nova note: Note that the Nova project has some additional rules around priority setting. All blueprints start out as a low priority. To get a higher priority, two core reviewers must sponsor a blueprint, agreeing that they will help review the resulting code to get it merged. At that point, the blueprint review team can consider raising the priority to be above Low. This is to set more realistic expectations about what blueprints we expect to get merged in a given part of the release cycle because it heavily depends on reviewer interest and availability.

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.


Blueprint Review Criteria

Once a blueprint has been targeted to a release milestone, it will be reviewed. Here is some criteria used when reviewing the blueprints.

A blueprint ...

  • is assigned to the person signing up to do the work
  • has been targeted to the milestone when the code is planned to be completed
  • is an appropriate feature for the project. This means it fits with the vision for the project overall. This is obviously very subjective, but the result should represent consensus.
  • includes enough detail to be able to complete an initial design review before approving the blueprint. In many cases, the design review may result in a discussion on the mailing list to work through details. A link to this discussion should be left in the whiteboard of the blueprint for reference. This initial design review should be completed before the blueprint is approved.
  • includes information that describes the user impact (or lack of). Between the blueprint and text that comes with the DocImpact flag in commits, the docs team should have everything they need to thoroughly document the feature.
  • has a scope that is not open ended. The scope of the blueprint must be clear and well defined such that it is easy to tell when to mark the blueprint as implemented.


Blueprints are not always required. Blueprints are used for tracking significant development efforts. In general, small and/or straight forward cleanups do not need blueprints. A blueprint should be filed if:

  • it impacts the release notes (would a user care?)
    • A feature has been added, removed, or changed ... For example, changes to:
      • configuration options
      • glance or cinder metadata properties that Nova consumes
      • public APIs
    • Affects deployments or upgrades ... For example, changes to:
      • how you migrate the DB schema
      • services that must be running
      • other upgrade procedures
  • it covers significant internal development or refactoring efforts


Once the review has been complete, the blueprint should be marked as approved and the priority should be set. A set priority is how we know from the blueprint list which ones have already been reviewed.


Please note, Nova are now using nova-specs to perform blueprint reviews, and their specific guidelines are included in the template in nova-specs

See also