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 Example Spec - The title of your specification
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.
