How to Write an Ubuntu Specification

This is an example Ubuntu specification, with comments on how to write a good Ubuntu specification. The better your spec, the better the chances that your ideas will be implemented in Ubuntu, and accepted by the distro team.

Status

• People: MarkShuttleworthLead, MattZimmermanSecondBR Created: 19/04/05BR Author: MarkShuttleworthBR Contributors: BR Status: BrainDump, UduBof, UbzSpecification, UbuntuSpecificationBR Priority: LowPriorityBR Branch: n/aBR Bug #: n/a

Introduction

This specification decribes the way we would like Ubuntu specifications to be written. It takes the form of a specification itself. You can see the SpecTemplate, which it is recommended you use for your own specifications in this system.

Rationale

As we develop new ideas for features in Ubuntu it's important to have a clear idea of the exact status of each idea. Putting this content in the wiki gives our community a chance to participate in the discussion and design of a feature, and increases the chance that community members will feel confident enough to start work on the implementation of the feature. A good specification allows community members who were not physically present at meetings discussing a topic to participate in the implementation of the spec.

Specification Structure

The spec is broken into a number of sections and sub-sections. We describe each of these in turn:

1. The title. A short heading for the spec, no more than 12 words.

2. The status metadata. This section contains some well-defined

   • metadata for the spec. It's important to put in as may flags and tags as possible that accurately describe the state and scope of the specification. These flags are used to generate reporting pages automatically. Please use as many flags as make sense for this spec

     from the following list: HighPriority, LowPriority, MediumPriority, UduBof, UbzSpecification, BrainDump, DraftSpecification, ApprovedSpecification, ImplementedSpecification, DistroSpecification, LaunchpadSpecification, CommunitySpecification, UbuntuTrack, KubuntuTrack, EdubuntuTrack, LaunchpadTrack.

3. Introduction. A brief introduction to the topic or spec. This

   • should not attempt to tell why the spec is being defined, just what is being specified.

4. Rationale: a summary of why this spec is being defined.

5. Scope and Use Cases. The use cases are not always required, but

   • in many cases they bring much better clarity to the scope and scale of the specification than could be obtained by talking in abstract terms.

6. Implementation Plan. This section is usually broken down into

   • subsections, such as the packages being affected, data and system migration where necessary, user interface requirements and pictures (photographs of drawings on paper work ell).