diff --git a/doc/source/blueprints.rst b/doc/source/blueprints.rst new file mode 100644 index 000000000000..7c501b6248a3 --- /dev/null +++ b/doc/source/blueprints.rst @@ -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 diff --git a/doc/source/index.rst b/doc/source/index.rst index 8ca7e1f866e0..8ec12a237c66 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -110,7 +110,7 @@ Development policies .. toctree:: :maxdepth: 1 - kilo.blueprints + blueprints policies Advanced testing and guides diff --git a/doc/source/kilo.blueprints.rst b/doc/source/kilo.blueprints.rst deleted file mode 100644 index 9b409286bdf5..000000000000 --- a/doc/source/kilo.blueprints.rst +++ /dev/null @@ -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)