f3121f0fb7
It seems that pbr's "warnerrors" isn't actually doing anything at the moment (I680b448471e687919d202e8f2abe57f8ba3b22ee) meaning we're able to commit docs with RST parser errors. Fix all these up in some minimal way (I have not audited content, just made it pass build). Link the specs in so they're referenced from the top level. Change-Id: Id67b9ea7ba8f49b43969c58ca3fb7fa1243538a4
89 lines
3.2 KiB
ReStructuredText
89 lines
3.2 KiB
ReStructuredText
================================
|
|
diskimage-builder Specifications
|
|
================================
|
|
|
|
Overview
|
|
========
|
|
|
|
This directory is used to hold approved design specifications for changes to
|
|
the diskimage-builder project. Reviews of the specs are done in gerrit, using a
|
|
similar workflow to how we review and merge changes to the code itself. For
|
|
specific policies around specification review, refer to the end of this
|
|
document.
|
|
|
|
The layout of this directory is::
|
|
|
|
specs/v<major_version>/
|
|
|
|
Where there are two sub-directories:
|
|
|
|
- specs/v<major_version>/approved: specifications approved but not yet
|
|
implemented
|
|
- specs/v<major_version>/implemented: implemented specifications
|
|
- specs/v<major_version>/backlog: unassigned specifications
|
|
|
|
The lifecycle of a specification
|
|
--------------------------------
|
|
|
|
Developers proposing a specification should propose a new file in the
|
|
``approved`` directory. diskimage-builder-core will review the change in the
|
|
usual manner for the project, and eventually it will get merged if a consensus
|
|
is reached.
|
|
|
|
When a specification has been implemented either the developer or someone
|
|
from diskimage-builder-core will move the implemented specification from the
|
|
``approved`` directory to the ``implemented`` directory. 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/v1/redirects``.
|
|
|
|
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.
|
|
|
|
Example specifications
|
|
----------------------
|
|
|
|
You can find an example spec in :doc:`v1/approved/v1-template`
|
|
|
|
Backlog specifications
|
|
----------------------
|
|
|
|
Additionally, we allow the proposal of specifications that do not have a
|
|
developer assigned to them. These are proposed for review in the same manner as
|
|
above, but are added to::
|
|
|
|
specs/backlog/approved
|
|
|
|
Specifications in this directory indicate the original author has either
|
|
become unavailable, or has indicated that they are not going to implement the
|
|
specification. The specifications found here are available as projects for
|
|
people looking to get involved with diskimage-builder. If you are interested in
|
|
claiming a spec, start by posting a review for the specification that moves it
|
|
from this directory to the next active release. Please set yourself as the new
|
|
`primary assignee` and maintain the original author in the `other contributors`
|
|
list.
|
|
|
|
Specification review policies
|
|
=============================
|
|
|
|
There are some special review policies which diskimage-builder-core will apply
|
|
when reviewing proposed specifications. They are:
|
|
|
|
Trivial specifications
|
|
----------------------
|
|
|
|
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. The decision of whether something is trivial or not is a
|
|
judgement made by the author or by consensus of the project cores, generally
|
|
trying to err on the side of spec creation.
|
|
|
|
Approved Specifications
|
|
=======================
|
|
|
|
.. toctree::
|
|
:glob:
|
|
|
|
v1/approved/*
|