|
|
|
@ -23,48 +23,58 @@ specs/<release>/approved
|
|
|
|
|
specs/<release>/implemented
|
|
|
|
|
implemented specifications
|
|
|
|
|
|
|
|
|
|
The lifecycle of a specification
|
|
|
|
|
--------------------------------
|
|
|
|
|
|
|
|
|
|
Developers proposing a specification should propose a new file in the
|
|
|
|
|
``approved`` directory. nova-specs-core will review the change in the usual
|
|
|
|
|
manner for the OpenStack project, and eventually it will get merged if a
|
|
|
|
|
consensus is reached. At this time the Launchpad blueprint is also approved.
|
|
|
|
|
The developer is then free to propose code reviews to implement their
|
|
|
|
|
specification. These reviews should be sure to reference the Launchpad
|
|
|
|
|
blueprint in their commit message for tracking purposes.
|
|
|
|
|
|
|
|
|
|
Once all code for the feature is merged into Nova, the Launchpad blueprint is
|
|
|
|
|
marked complete. As the developer of an approved specification it is your
|
|
|
|
|
responsibility to mark your blueprint complete when all of the required
|
|
|
|
|
patches have merged.
|
|
|
|
|
|
|
|
|
|
Periodically, someone from nova-specs-core will move implemented specifications
|
|
|
|
|
from the ``approved`` directory to the ``implemented`` directory. Whilst
|
|
|
|
|
individual developers are welcome to propose this move for their implemented
|
|
|
|
|
specifications, we have generally just done this in a batch at the end of the
|
|
|
|
|
release cycle. It is important to create redirects when this is done so that
|
|
|
|
|
existing links to the approved specification are not broken. Redirects aren't
|
|
|
|
|
symbolic links, they are defined in a file which sphinx consumes. An example
|
|
|
|
|
is at ``specs/kilo/redirects``.
|
|
|
|
|
|
|
|
|
|
.. note:: Use the ``tox -e move-implemented-specs`` target at the end of each
|
|
|
|
|
release to automatically move completed specs and populate the
|
|
|
|
|
redirects file for that release. For example::
|
|
|
|
|
|
|
|
|
|
tox -r -e move-implemented-specs -- --dry-run --verbose newton
|
|
|
|
|
|
|
|
|
|
Remove the ``--dry-run`` flag to perform the actual file
|
|
|
|
|
moves/writes.
|
|
|
|
|
|
|
|
|
|
This directory structure allows you to see what we thought about doing,
|
|
|
|
|
decided to do, and actually got done. Users interested in functionality in a
|
|
|
|
|
given release should only refer to the ``implemented`` directory.
|
|
|
|
|
|
|
|
|
|
The lifecycle of a specification
|
|
|
|
|
--------------------------------
|
|
|
|
|
|
|
|
|
|
Developers proposing a specification should propose a new file in the
|
|
|
|
|
``approved`` directory. `nova-specs-core
|
|
|
|
|
<https://review.opendev.org/#/admin/groups/302,members>`_ will review the
|
|
|
|
|
change in the usual manner for the OpenStack project, and eventually it will
|
|
|
|
|
get merged if a consensus is reached.
|
|
|
|
|
|
|
|
|
|
At this time the Launchpad blueprint is also "Definition" approved. The
|
|
|
|
|
developer is then free to propose code reviews to implement their
|
|
|
|
|
specification. These reviews should be sure to reference the Launchpad
|
|
|
|
|
blueprint in their commit message for tracking purposes.
|
|
|
|
|
|
|
|
|
|
.. note:: The launchpad blueprint's "Definition" approval indicates that the
|
|
|
|
|
nova-specs-core team agrees with the technical aspects of the
|
|
|
|
|
proposal ("if we are going to do this, this is how"). The blueprint's
|
|
|
|
|
"Direction" approval is a separate indication of commitment to the
|
|
|
|
|
targeted release ("we want to do this now"). It is possible to have a
|
|
|
|
|
specification and blueprint "Definition" approved, but not have its
|
|
|
|
|
"Direction" approved due to subsequent planning activities. In such
|
|
|
|
|
cases, the blueprint (and any unmerged code) could be deferred for
|
|
|
|
|
consideration in a future release.
|
|
|
|
|
|
|
|
|
|
.. todo:: Document the specifics of these "planning activities".
|
|
|
|
|
|
|
|
|
|
Once all code for the feature is merged into Nova, the Launchpad blueprint is
|
|
|
|
|
marked "Implemented" by a nova maintainer.
|
|
|
|
|
|
|
|
|
|
At the end of the release cycle, implemented specifications are moved from the
|
|
|
|
|
``approved`` directory to the ``implemented`` directory, creating redirects so
|
|
|
|
|
that existing links to the approved specification are not broken. (Redirects
|
|
|
|
|
aren't symbolic links, they are defined in a file which sphinx consumes. An
|
|
|
|
|
example is at ``specs/stein/redirects``.)
|
|
|
|
|
|
|
|
|
|
We use the ``tox -e move-implemented-specs`` target at the end of each release
|
|
|
|
|
to automatically move completed specs and populate the redirects file for that
|
|
|
|
|
release. For example::
|
|
|
|
|
|
|
|
|
|
tox -r -e move-implemented-specs -- --dry-run --verbose train
|
|
|
|
|
|
|
|
|
|
Remove the ``--dry-run`` flag to perform the actual file moves/writes. Then
|
|
|
|
|
commit the changes and submit the review to gerrit as usual.
|
|
|
|
|
|
|
|
|
|
Example specifications
|
|
|
|
|
----------------------
|
|
|
|
|
|
|
|
|
|
You can find an example spec for a given release in
|
|
|
|
|
You can find a spec template for a given release in
|
|
|
|
|
``specs/<release>-template.rst``.
|
|
|
|
|
|
|
|
|
|
Backlog specifications
|
|
|
|
@ -91,7 +101,8 @@ a fashion similar to the process for ``implemented`` specs above. The
|
|
|
|
|
|
|
|
|
|
tox -e move-spec -- --dry-run --verbose specs/backlog/my-great-idea.rst specs/train/approved
|
|
|
|
|
|
|
|
|
|
Remove the ``--dry-run`` option to perform the actual file moves/writes.
|
|
|
|
|
Remove the ``--dry-run`` option to perform the actual file moves/writes. Then
|
|
|
|
|
commit the changes and submit the review to gerrit as usual.
|
|
|
|
|
|
|
|
|
|
.. note:: Please do not use ``move-spec`` to repropose an unimplemented spec
|
|
|
|
|
from one release to another. Instead follow the instructions at
|
|
|
|
@ -140,12 +151,12 @@ For more information about working with gerrit, see
|
|
|
|
|
http://docs.openstack.org/infra/manual/developers.html#development-workflow
|
|
|
|
|
|
|
|
|
|
To validate that the specification is syntactically correct (i.e. get more
|
|
|
|
|
confidence in the Jenkins result), please execute the following command::
|
|
|
|
|
confidence in the Zuul result), please execute the following command::
|
|
|
|
|
|
|
|
|
|
$ tox
|
|
|
|
|
|
|
|
|
|
After running ``tox``, the documentation will be available for viewing in HTML
|
|
|
|
|
format in the ``doc/build/`` directory.
|
|
|
|
|
format in the ``doc/build/html/`` directory.
|
|
|
|
|
|
|
|
|
|
Specification review policies
|
|
|
|
|
=============================
|
|
|
|
@ -160,34 +171,41 @@ Proposed changes which are trivial (very small amounts of code) and don't
|
|
|
|
|
change any of our public APIs are sometimes not required to provide a
|
|
|
|
|
specification. In these cases a Launchpad blueprint is considered sufficient.
|
|
|
|
|
These proposals are approved during the `Open Discussion` portion of the
|
|
|
|
|
weekly nova IRC meeting. If you think your proposed feature is trivial and
|
|
|
|
|
weekly `nova IRC meeting`_. If you think your proposed feature is trivial and
|
|
|
|
|
meets these requirements, we recommend you bring it up for discussion there
|
|
|
|
|
before writing a full specification.
|
|
|
|
|
|
|
|
|
|
Previously approved specifications
|
|
|
|
|
----------------------------------
|
|
|
|
|
|
|
|
|
|
`Specifications are only approved for a single release`. If your specification
|
|
|
|
|
was previously approved but not implemented (or not completely implemented),
|
|
|
|
|
then you must seek re-approval for the specification. You can re-propose your
|
|
|
|
|
specification by doing the following:
|
|
|
|
|
**Specifications are only approved for a single release**. If your
|
|
|
|
|
specification was previously approved but not implemented (or not completely
|
|
|
|
|
implemented), then you must seek re-approval for the specification. You can
|
|
|
|
|
re-propose your specification by doing the following:
|
|
|
|
|
|
|
|
|
|
* Copy (not move) your specification to the right directory for the current release.
|
|
|
|
|
* Update the document to comply with the new template.
|
|
|
|
|
* If there are no functional changes to the specification (only template changes) then add the `Previously-approved: <release>` tag to your commit message.
|
|
|
|
|
* Update the document to comply with the new template; modify the History
|
|
|
|
|
section; select a new :ref:`feature liaison <feature-liaisons>` if needed.
|
|
|
|
|
* If there are no functional changes to the specification (only template
|
|
|
|
|
changes) then add the ``Previously-approved: <release>`` tag to your commit
|
|
|
|
|
message.
|
|
|
|
|
* Send for review.
|
|
|
|
|
* nova-specs-core will merge specifications which meet these requirements with a single +2.
|
|
|
|
|
* These specifications are subject to the same review process as any other.
|
|
|
|
|
They need to be reevaluated to ensure the technical aspects are still valid
|
|
|
|
|
and that we still wish to implement it given resource constraints and other
|
|
|
|
|
priorities.
|
|
|
|
|
|
|
|
|
|
Specifications which depend on merging code in other OpenStack projects
|
|
|
|
|
-----------------------------------------------------------------------
|
|
|
|
|
|
|
|
|
|
For specifications `that depend on code in other OpenStack projects merging`
|
|
|
|
|
For specifications **that depend on code in other OpenStack projects merging**
|
|
|
|
|
we will not approve the nova specification until the code in that other project
|
|
|
|
|
has merged. The best example of this is Cinder and Neutron drivers. To
|
|
|
|
|
indicate your specification is in this state, please use the Depends-On git
|
|
|
|
|
commit message tag. The correct format is `Depends-On: <change id of other
|
|
|
|
|
work>`. nova-specs-core can approve the specification at any time, but it wont
|
|
|
|
|
merge until the code we need to land in the other project has merged as well.
|
|
|
|
|
commit message tag. The correct format is ``Depends-On: <change id of other
|
|
|
|
|
work>``. nova-specs-core can approve the specification at any time, but it
|
|
|
|
|
won't merge until the code we need to land in the other project has merged as
|
|
|
|
|
well.
|
|
|
|
|
|
|
|
|
|
New libvirt image backends
|
|
|
|
|
--------------------------
|
|
|
|
@ -196,5 +214,90 @@ There are some cases where an author might propose adding a new libvirt
|
|
|
|
|
driver image storage backend which does not require code in other OpenStack
|
|
|
|
|
projects. An example was the ceph image storage backend, if we treat that as
|
|
|
|
|
separate from the ceph volume support code. Implementing a new image storage
|
|
|
|
|
backend in the libvirt drive always requires a specification because of our
|
|
|
|
|
backend in the libvirt driver always requires a specification because of our
|
|
|
|
|
historical concerns around adequate CI testing.
|
|
|
|
|
|
|
|
|
|
.. todo:: Write a fleshed-out section on the roles and responsibilities of the
|
|
|
|
|
nova team, including things like the two +2 rule, the same-company
|
|
|
|
|
trifecta rule, whether +2ing a spec represents a commitment to review
|
|
|
|
|
the corresponding code, etc.
|
|
|
|
|
|
|
|
|
|
.. _feature-liaisons:
|
|
|
|
|
|
|
|
|
|
Feature Liaison FAQ
|
|
|
|
|
===================
|
|
|
|
|
|
|
|
|
|
In Ussuri, a mandatory "Feature Liaison" section was added to the spec
|
|
|
|
|
template. This section attempts to address some of the questions around this
|
|
|
|
|
concept.
|
|
|
|
|
|
|
|
|
|
What does a Feature Liaison do?
|
|
|
|
|
By signing up to be a feature liaison for a spec, you're agreeing to help
|
|
|
|
|
shepherd the feature through the development process. This has different
|
|
|
|
|
implications depending on the identity/role of the spec owner and your
|
|
|
|
|
relative roles in the project. Some examples:
|
|
|
|
|
|
|
|
|
|
* **Liaison for an inexperienced contributor:** This is the case for which
|
|
|
|
|
the liaison concept was conceived. In this case the liaison's job is to
|
|
|
|
|
mentor the spec owner, keep an eye on their progress, let them know when
|
|
|
|
|
they're missing some obscure (or not-so-obscure) part of the process, help
|
|
|
|
|
them understand what "review-ready" means, etc. You are also committing to
|
|
|
|
|
reviewing their code -- or at the very least helping them track down
|
|
|
|
|
suitable reviewers.
|
|
|
|
|
* **Designating yourself as your own liaison:** If you're a nova core or
|
|
|
|
|
experienced nova developer, you're already culturally indoctrinated. You
|
|
|
|
|
know how to navigate the process. You know how to ask for reviews. You
|
|
|
|
|
still can't +1/+2 your own code.
|
|
|
|
|
* **Core or experienced nova dev procures separate liaison:** Since you don't
|
|
|
|
|
need the mentorship aspect, your liaison in this case is really just
|
|
|
|
|
committing to doing reviews. While not necessary, it might be nice to get
|
|
|
|
|
that kind of commitment up front.
|
|
|
|
|
|
|
|
|
|
The above is not exhaustive; clearly there is a lot of middle ground between
|
|
|
|
|
an inexperienced contributor and a nova-core as a spec owner. It should
|
|
|
|
|
hopefully be fairly obvious how the liaison's role shifts in that middle
|
|
|
|
|
ground. If further clarification is necessary, please edit this doc.
|
|
|
|
|
|
|
|
|
|
Feature Liaison need not be a nova-core.
|
|
|
|
|
The role of a liaison does not require +2 powers. A feature liaison should be
|
|
|
|
|
taken to mean "experienced nova developer capable of doing the job". That
|
|
|
|
|
said, whereas nova cores implicitly match that description by virtue of
|
|
|
|
|
having been made cores, non-cores proposed as liaisons should be evaluated on
|
|
|
|
|
a case-by-case basis (by the reviewers of the spec) as part of the spec
|
|
|
|
|
review process to determine whether they qualify. For the most part, "we know
|
|
|
|
|
who you are". (Note that in cases where an experienced non-core is a liaison
|
|
|
|
|
for someone else's feature, they're still signing up to do reviews, which are
|
|
|
|
|
still valuable despite maxing out at +1.)
|
|
|
|
|
|
|
|
|
|
How do I find a Feature Liaison?
|
|
|
|
|
If you do not already have agreement from someone to act as your liaison,
|
|
|
|
|
note this in your spec draft. You may accelerate the process by communicating
|
|
|
|
|
with the nova development team on IRC (``#openstack-nova``), in a `nova IRC
|
|
|
|
|
meeting`_, or via the `openstack-discuss`_ mailing list.
|
|
|
|
|
|
|
|
|
|
What about specless blueprints?
|
|
|
|
|
We'll put the name of the feature liaison into the blueprint description.
|
|
|
|
|
It's not as automatically-enforceable as the template checker, but oh well.
|
|
|
|
|
|
|
|
|
|
How does liaison-hood relate to blueprint approval and prioritization?
|
|
|
|
|
It really doesn't. If you sign up to be a liaison for blueprint X, the nova
|
|
|
|
|
team may still decide blueprint X is a nonstarter for technical reasons; or
|
|
|
|
|
that we don't have the bandwidth to get it done this cycle in light of other
|
|
|
|
|
priorities. You're really just saying, "If this goes, I'm on it."
|
|
|
|
|
|
|
|
|
|
How does liaison-hood relate to the gerrit review for the spec?
|
|
|
|
|
A liaison can (and really should, though it's not a hard requirement (yet))
|
|
|
|
|
review and +2/+1 a spec for which they're the liaison (but not the owner).
|
|
|
|
|
However, everyone is still encouraged to review and approve other specs as
|
|
|
|
|
well (otherwise nothing will get done) (also see below). (It would be nice if
|
|
|
|
|
an upvote on a spec patch also acted as a commitment to review the
|
|
|
|
|
corresponding code, but the liaison process does not attempt to address
|
|
|
|
|
that (yet).)
|
|
|
|
|
|
|
|
|
|
Am I still allowed to care about / review / shepherd other approved features for which I didn't volunteer to be a liaison?
|
|
|
|
|
Of course. The point of this is the converse: If you *don't* pay attention to
|
|
|
|
|
features you *did* sign up for, people will draw moustaches on pictures of
|
|
|
|
|
your face. Or horns, if you already have a moustache.
|
|
|
|
|
|
|
|
|
|
.. _`nova IRC meeting`: https://wiki.openstack.org/wiki/Meetings/Nova
|
|
|
|
|
.. _openstack-discuss: http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss
|
|
|
|
|