Make blueprints doc a reference for nova blueprints
Previously kilo.blueprints was a document to propose a change to the blueprints process. Turn the document into a reference for blueprints, specs and priorities in nova. * Just state current policy instead of references to how it was before. This information will still be around in the git history if we never need to look it up. * Now that we have been doing this for a cycle we don't need hypothetical examples anymore. * Make this reflect the fact that we just use an etherpad to track * priority reviews. Change-Id: I0d6e568fe1a8ef40de1d7f7d7e45260b1400e407
This commit is contained in:
Joe Gordon
65
doc/source/blueprints.rst
Normal file
65
doc/source/blueprints.rst
Normal file
@@ -0,0 +1,65 @@
|
||||
==================================
|
||||
Blueprints, Specs and Priorities
|
||||
==================================
|
||||
|
||||
Like most OpenStack projects, Nova uses `blueprints`_ and specifications (specs) to track new
|
||||
features, but not all blueprints require a spec. This document covers when a spec is needed.
|
||||
|
||||
|
||||
.. note:: Nova's specs live at: `specs.openstack.org`_
|
||||
|
||||
|
||||
.. _`blueprints`: http://docs.openstack.org/infra/manual/developers.html#working-on-specifications-and-blueprints
|
||||
.. _`specs.openstack.org`: http://specs.openstack.org/openstack/nova-specs/
|
||||
|
||||
|
||||
Specs
|
||||
=====
|
||||
|
||||
A spec is needed for any feature that requires a design discussion. All
|
||||
features need a blueprint but not all blueprints require a spec.
|
||||
|
||||
If a new feature is straightforward enough that it doesn't need any design
|
||||
discussion, then no spec is required. In order to provide the sort of
|
||||
documentation that would otherwise be provided via a spec, the commit
|
||||
message should include a ``DocImpact`` flag and a thorough description
|
||||
of the feature from a user/operator perspective.
|
||||
|
||||
Guidelines for when a feature doesn't need a spec.
|
||||
|
||||
* Is the feature a single self contained change?
|
||||
|
||||
* If the feature touches code all over the place, it probably should have
|
||||
a design discussion.
|
||||
* If the feature is big enough that it needs more then one commit, it
|
||||
probably should have a design discussion.
|
||||
* Not an API change.
|
||||
|
||||
* API changes always require a design discussion.
|
||||
|
||||
|
||||
Project Priorities
|
||||
===================
|
||||
|
||||
* Pick several project priority themes, in the form of use cases, to help us
|
||||
prioritize work
|
||||
|
||||
* Generate list of improvement blueprints based on the themes
|
||||
* Produce rough draft of list going into summit and finalize the list at
|
||||
the summit
|
||||
* Publish list of project priorities and look for volunteers to work on them
|
||||
* Update spec template to include
|
||||
|
||||
* Specific use cases
|
||||
* State if the spec is project priority or not
|
||||
* Keep an up to date list of project priority blueprints that need code review in an etherpad.
|
||||
|
||||
* Consumers of project priority and project priority blueprint lists:
|
||||
|
||||
* Reviewers looking for direction of where to spend their blueprint review
|
||||
time. If a large subset of nova-core doesn't use the project
|
||||
priorities it means the core team is not aligned properly and should
|
||||
revisit the list of project priorities
|
||||
* The blueprint approval team, to help find the right balance of blueprints
|
||||
* Contributors looking for something to work on
|
||||
* People looking for what they can expect in the next release
|
||||
@@ -110,7 +110,7 @@ Development policies
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
kilo.blueprints
|
||||
blueprints
|
||||
policies
|
||||
|
||||
Advanced testing and guides
|
||||
|
||||
@@ -1,249 +0,0 @@
|
||||
==================
|
||||
Blueprints in Kilo
|
||||
==================
|
||||
|
||||
===========================
|
||||
When is a blueprint needed?
|
||||
===========================
|
||||
|
||||
|
||||
Juno
|
||||
-----
|
||||
|
||||
Every new feature needs a blueprint, and all blueprints need a spec. If the
|
||||
blueprint is small, then the spec should be small. We added the specs
|
||||
workflow to help improve the design discussion part of blueprints, but
|
||||
are using it as a documentation tool as well.
|
||||
|
||||
|
||||
Problem
|
||||
--------
|
||||
|
||||
The specs repo is very good for hashing out design, but if a new feature
|
||||
doesn't need any design discussion, requiring a spec is a significant overhead.
|
||||
If the spec is just used for documentation and not design discussion, we are
|
||||
adding a whole extra round of reviewing when the documentation can just be done
|
||||
in the commit message.
|
||||
|
||||
Kilo
|
||||
-----
|
||||
|
||||
A spec is needed for any feature that requires a design discussion. All
|
||||
features need a blueprint but not all blueprints require a spec.
|
||||
|
||||
If a new feature is straightforward enough that it doesn't need any design
|
||||
discussion, then no spec is required. In order to provide the sort of
|
||||
documentation that would otherwise be provided via a spec, the commit
|
||||
message should include a ``DocImpact`` flag and a thorough description
|
||||
of the feature from a user/operator perspective.
|
||||
|
||||
Guidelines for when a feature doesn't need a spec.
|
||||
|
||||
* Is the feature a single self contained change?
|
||||
|
||||
* If the feature touches code all over the place, it probably should have
|
||||
a design discussion.
|
||||
* If the feature is big enough that it needs more then one commit, it
|
||||
probably should have a design discussion.
|
||||
* Not an API change.
|
||||
|
||||
* API changes always require a design discussion.
|
||||
|
||||
|
||||
Examples
|
||||
---------
|
||||
|
||||
Juno blueprints where no spec would be needed in Kilo:
|
||||
|
||||
* backportable-db-migrations-juno.rst
|
||||
|
||||
* no discussion needed, this is now standard practice
|
||||
* add-all-in-list-operator-to-extra-spec-ops.rst
|
||||
|
||||
* Trivial self contained change
|
||||
* hyper-v-console-log.rst
|
||||
|
||||
* self contained, straight forward feature parity fix
|
||||
* hyper-v-soft-reboot.rst
|
||||
|
||||
* self contained, straight forward feature parity fix
|
||||
* io-ops-weight.rst
|
||||
|
||||
* self contained, both the motivation and usage details are easily explained
|
||||
in a commit message
|
||||
* per-aggregate-filters.rst
|
||||
|
||||
* self contained, adds new filters similar to ones we already have
|
||||
* restrict-image-isolation-with-defined-keys.rst
|
||||
|
||||
* self contained improvement to a scheduler filter
|
||||
|
||||
Juno blueprints where a spec would still be needed in Kilo:
|
||||
|
||||
* add-ironic-driver.rst
|
||||
* config-drive-image-property.rst
|
||||
* enabled-qemu-memballoon-stats.rst
|
||||
* db2-database.rst
|
||||
* cross-service-request-id.rst
|
||||
* clean-logs.rst
|
||||
* i18n-enablement.rst
|
||||
* instance-network-info-hook.rst
|
||||
* encryption-with-barbican.rst
|
||||
* juno-slaveification.rst
|
||||
* extensible-resource-tracking.rst
|
||||
* cold-migration-with-target.rst
|
||||
* allow-image-to-be-specified-during-rescue.rst
|
||||
* add-differencing-vhdx-resize-support.rst
|
||||
* add-virtio-scsi-bus-for-bdm.rst
|
||||
* compute-manager-objects-juno.rst
|
||||
* allocation-ratio-to-resource-tracker.rst
|
||||
* better-support-for-multiple-networks.rst
|
||||
* nova-pagination.rst
|
||||
* convert_ec2_api_to_use_nova_objects.rst
|
||||
* make-resource-tracker-use-objects.rst
|
||||
* object-subclassing.rst
|
||||
* virt-objects-juno.rst
|
||||
* scheduler-lib.rst
|
||||
* return-status-for-hypervisor-node.rst
|
||||
* server-count-api.rst
|
||||
* server-group-quotas.rst
|
||||
* ec2-volume-and-snapshot-tags.rst
|
||||
* enforce-unique-instance-uuid-in-db.rst
|
||||
* find-host-and-evacuate-instance.rst
|
||||
* input-output-based-numa-scheduling.rst
|
||||
* libvirt-domain-listing-speedup.rst
|
||||
* libvirt-disk-discard-option.rst
|
||||
* libvirt-driver-class-refactor.rst
|
||||
* libvirt-lxc-user-namespaces.rst
|
||||
* libvirt-driver-domain-metadata.rst
|
||||
* libvirt-sheepdog-backed-instances.rst
|
||||
* libvirt-start-lxc-from-block-devices.rst
|
||||
* libvirt-volume-snap-network-disk.rst
|
||||
* log-request-id-mappings.rst
|
||||
* lvm-ephemeral-storage-encryption.rst
|
||||
* v2-on-v3-api.rst
|
||||
* v3-api-schema.rst
|
||||
* v3-diagnostics.rst
|
||||
* tag-instances.rst
|
||||
* support-cinderclient-v2.rst
|
||||
* use-oslo-vmware.rst
|
||||
* return-all-servers-during-multiple-create.rst
|
||||
* remove-cast-to-schedule-run-instance.rst
|
||||
* persistent-resource-claim.rst
|
||||
* serial-ports.rst
|
||||
* servers-list-support-multi-status.rst
|
||||
* xenapi-vcpu-topology.rst
|
||||
* selecting-subnet-when-creating-vm.rst
|
||||
* refactor-network-api.rst
|
||||
* migrate-libvirt-volumes.rst
|
||||
* move-prep-resize-to-conductor.rst
|
||||
* nfv-multiple-if-1-net.rst
|
||||
* on-demand-compute-update.rst
|
||||
* pci-passthrough-sriov.rst
|
||||
* quiesced-image-snapshots-with-qemu-guest-agent.rst
|
||||
* rbd-clone-image-handler.rst
|
||||
* rescue-attach-all-disks.rst
|
||||
* standardize-nova-image.rst
|
||||
* string-field-max-length.rst
|
||||
* support-console-log-migration.rst
|
||||
* use-libvirt-storage-pools.rst
|
||||
* user-defined-shutdown.rst
|
||||
* vif-vhostuser.rst
|
||||
* virt-driver-cpu-pinning.rst
|
||||
* virt-driver-large-pages.rst
|
||||
* virt-driver-numa-placement.rst
|
||||
* virt-driver-vcpu-topology.rst
|
||||
* vmware-driver-ova-support.rst
|
||||
* vmware-ephemeral-disk-support.rst
|
||||
* vmware-hot-plug.rst
|
||||
* vmware-spbm-support.rst
|
||||
* vmware-vsan-support.rst
|
||||
* websocket-proxy-to-host-security.rst
|
||||
* xenapi-set-ipxe-url-as-img-metadata.rst
|
||||
|
||||
|
||||
===================
|
||||
Project Priorities
|
||||
===================
|
||||
|
||||
Icehouse
|
||||
--------
|
||||
|
||||
Tried requiring cores to sign up to review specific blueprints during
|
||||
the blueprint approval process, but almost no one signed up so we abandoned
|
||||
the idea in Juno.
|
||||
|
||||
Juno
|
||||
------
|
||||
|
||||
* Poor prioritization of our 88 blueprints, attempts to get feedback via
|
||||
etherpads largely went unnoticed
|
||||
* Implicit notion of what nova as a project would like to accomplish for the next
|
||||
release. But it was too implicit and everyone had a slightly different list
|
||||
* Project priorities are not factored into the blueprint review process
|
||||
|
||||
Problem
|
||||
--------
|
||||
|
||||
* Poor job at prioritizing. Our current process doesn't provide the nova team
|
||||
a good way to prioritize efforts. As a team we would like to identify and
|
||||
prioritize blueprints that can we deem as project priorities
|
||||
* No easy way to communicate to contributors what the project as a whole
|
||||
thinks we should be working on for a given release, making it hard to
|
||||
focus our efforts in project priorities
|
||||
* Difficult for contributors to understand the importance of work that isn't
|
||||
strictly about new features for new use cases
|
||||
|
||||
Kilo
|
||||
-----
|
||||
|
||||
* Pick several project priority themes, in the form of use cases, to help us
|
||||
prioritize work
|
||||
|
||||
* Generate list of improvement blueprints based on the themes
|
||||
* Produce rough draft of list going into summit and finalize the list at
|
||||
the summit
|
||||
* Publish list of project priorities and look for volunteers to work on them
|
||||
* Update spec template to include
|
||||
|
||||
* Specific use cases
|
||||
* State if the spec is project priority or not
|
||||
* Keep an up to date list of project priority blueprints that need code review
|
||||
|
||||
* List will be a YAML file so it is both human and machine readable
|
||||
* List will live in nova-specs
|
||||
* Support ability to build tools to consume this list
|
||||
* Consumers of project priority and project priority blueprint lists:
|
||||
|
||||
* Reviewers looking for direction of where to spend their blueprint review
|
||||
time. If a large subset of nova-core doesn't use the project
|
||||
priorities it means the core team is not aligned properly and should
|
||||
revisit the list of project priorities
|
||||
* The blueprint approval team, to help find the right balance of blueprints
|
||||
* Contributors looking for something to work on
|
||||
* People looking for what they can expect in the next release
|
||||
|
||||
Note that the specific priorities for Kilo can be found here:
|
||||
http://specs.openstack.org/openstack/nova-specs/priorities/kilo-priorities.html
|
||||
|
||||
Examples
|
||||
---------
|
||||
|
||||
Project priorities:
|
||||
|
||||
* Stability. As a user I don't want things to randomly fail.
|
||||
* Debugging. As an operator when something goes wrong, the logs should
|
||||
be helpful for debugging.
|
||||
* Improved python client. As a user, I want a friendly python SDK and CLI. It
|
||||
should be easy to use as possible.
|
||||
* Live upgrades. As an operator I want to be able to upgrade nova
|
||||
without any downtime.
|
||||
* Fault tolerance. As an operator I don't want any single hardware or software
|
||||
failure to break nova.
|
||||
* Performance/Scalability. As a operator I want nova to scale and perform well.
|
||||
|
||||
Project priority blueprints:
|
||||
|
||||
* Convert X to Objects (Live upgrades -- via minimal db downtime upgrades)
|
||||
* Remove stacktraces from nova-api (Debugging)
|
||||
* Improve usage of SQLAlchemy: https://wiki.openstack.org/wiki/Openstack_and_SQLAlchemy#ORM_Quick_Wins_Proof_of_Concept (Performance)
|
||||
Reference in New Issue
Block a user