83 lines
3.1 KiB
ReStructuredText
83 lines
3.1 KiB
ReStructuredText
|
=======
|
||
|
|
README
|
||
|
|
=======
|
||
|
|
|
||
|
|
diskimage-builder Specifications
|
||
|
|
================================
|
||
|
|
|
||
|
|
|
||
|
|
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 ``specs/template.rst``.
|
||
|
|
|
||
|
|
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.
|