SpecSpec
Size: 3058
Comment: changed SpecificationTemplate (No page) to SpecTemplate
|
Size: 4867
Comment:
|
Deletions are marked like this. | Additions are marked like this. |
Line 1: | Line 1: |
= How to Write an Ubuntu Specification = | * '''Launchpad Entry''': https://launchpad.net/distros/ubuntu/+spec/foo * '''Created''': [[Date(2005-10-25T15:45:54Z)]] by MatthewEast * '''Contributors''': MatthewEast * '''Packages affected''': * '''See also''': SpecTemplate |
Line 3: | Line 7: |
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. |
== Summary == |
Line 7: | Line 9: |
== Status == People: MarkShuttleworthLead, MattZimmermanSecond[[BR]] Created: 19/04/05[[BR]] Author: MarkShuttleworth[[BR]] Contributors: [[BR]] Status: BrainDump, UduBof, UbzSpecification, UbuntuSpecification[[BR]] Priority: LowPriority[[BR]] Branch: n/a[[BR]] 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. |
This specification describes the way we would like Ubuntu specifications to be written. It takes the form of a specification itself. |
Line 26: | Line 13: |
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. |
As we develop new ideas for features in Ubuntu, it's important to be able to communicate them clearly. This serves the purpose of making it clear what the feature is about, and allowing people to evolve an implementation strategy for it. |
Line 35: | Line 15: |
== Specification Structure == | 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. |
Line 37: | Line 17: |
The spec is broken into a number of sections and sub-sections. We describe each of these in turn: |
A good specification also allows community members who were not physically present at meetings discussing a topic to participate in the implementation of the spec. |
Line 40: | Line 19: |
1. '''The title'''. A short heading for the spec, no more than 12 words. | Bottom line: the better your spec, the better the chances that your ideas will clearly understood by the review team. |
Line 42: | Line 21: |
1. '''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. |
== Use Cases == * Bob is the maintainer for the boot process for Ubuntu. In the Dapper cycle, he would like to work on getting the boot time down to two seconds from boot manager to GDM screen. He creates an entry for the specification in Launchpad, proposes it for the UBZ sprint, and starts writing out a braindump of it in the Ubuntu wiki. Magnus, who is in charge of UBZ scheduling, thinks it sounds fishy but approves it to make sure that the change is discussed and documented properly. He marks it as priority Medium because he isn't sure Bob will have time free for implementing it during Dapper. * Pedro works on Malone, in Launchpad. Before UBZ, he remembers that the dependency handling in the bug tracker is really not optimal. He writes out a Summary and Rationale in a Launchpad wiki page, registers it as a specification in Launchpad, and suggests it for UBZ. Monica, Launchpad manageress, thinks that this is really not the time to be talking about it and rejects the application for UBZ. He then indicates it for the next conference, UBB, and marks its priority is Low. * Jason is an Ubuntu and Rosetta user. He has noticed that changes made to translations are making their way into language packs but not to the upstream versions, and adds a specification that describes a way for getting upstream to use language packs. Monica also has a plan for this but hadn't described it in a spec, so she adds it to the UBZ spec list, and adds Carlos, Rosetta maintainer, as drafter for it. == Scope == This specification covers feature specifications for Ubuntu and Launchpad. It is not meant as a more general specifical format. == Design == |
Line 66: | Line 49: |
== Implementation == To implement a specification, the assignee should observe the use cases carefully, and follow the design specified. He should make note of places in which he has strayed from the design section, adding rationale describing why this happened. This is important so that next iterations of this specification (and new specifications that touch upon this subject) can use the specification as a reference. The implementation is very dependent on the type of feature to be implemented. Refer to the team leader for further suggestions and guidance on this topic. == Outstanding Issues == The specification process requires experienced people to drive it. More documentation on the process should be produced. The drafting of a specification requires english skills and a very good understanding of the problem. It must also describe things to an extent that someone else could implement. This is a difficult set of conditions to ensure throughout all the specifications added. There is a lot of difficulty in gardening obsolete, unwanted and abandoned specifications in the Wiki. == BoF agenda and discussion == We'll have a first public session on this on the first Monday in UBZ. |
Launchpad Entry: https://launchpad.net/distros/ubuntu/+spec/foo
Created: Date(2005-10-25T15:45:54Z) by MatthewEast
Contributors: MatthewEast
Packages affected:
See also: SpecTemplate
Summary
This specification describes the way we would like Ubuntu specifications to be written. It takes the form of a specification itself.
Rationale
As we develop new ideas for features in Ubuntu, it's important to be able to communicate them clearly. This serves the purpose of making it clear what the feature is about, and allowing people to evolve an implementation strategy for it.
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 also allows community members who were not physically present at meetings discussing a topic to participate in the implementation of the spec.
Bottom line: the better your spec, the better the chances that your ideas will clearly understood by the review team.
Use Cases
- Bob is the maintainer for the boot process for Ubuntu. In the Dapper cycle, he would like to work on getting the boot time down to two seconds from boot manager to GDM screen. He creates an entry for the specification in Launchpad, proposes it for the UBZ sprint, and starts writing out a braindump of it in the Ubuntu wiki. Magnus, who is in charge of UBZ scheduling, thinks it sounds fishy but approves it to make sure that the change is discussed and documented properly. He marks it as priority Medium because he isn't sure Bob will have time free for implementing it during Dapper.
- Pedro works on Malone, in Launchpad. Before UBZ, he remembers that the dependency handling in the bug tracker is really not optimal. He writes out a Summary and Rationale in a Launchpad wiki page, registers it as a specification in Launchpad, and suggests it for UBZ. Monica, Launchpad manageress, thinks that this is really not the time to be talking about it and rejects the application for UBZ. He then indicates it for the next conference, UBB, and marks its priority is Low.
- Jason is an Ubuntu and Rosetta user. He has noticed that changes made to translations are making their way into language packs but not to the upstream versions, and adds a specification that describes a way for getting upstream to use language packs. Monica also has a plan for this but hadn't described it in a spec, so she adds it to the UBZ spec list, and adds Carlos, Rosetta maintainer, as drafter for it.
Scope
This specification covers feature specifications for Ubuntu and Launchpad. It is not meant as a more general specifical format.
Design
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.
Rationale: a summary of why this spec is being defined.
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.
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).
Implementation
To implement a specification, the assignee should observe the use cases carefully, and follow the design specified. He should make note of places in which he has strayed from the design section, adding rationale describing why this happened. This is important so that next iterations of this specification (and new specifications that touch upon this subject) can use the specification as a reference.
The implementation is very dependent on the type of feature to be implemented. Refer to the team leader for further suggestions and guidance on this topic.
Outstanding Issues
The specification process requires experienced people to drive it. More documentation on the process should be produced.
The drafting of a specification requires english skills and a very good understanding of the problem. It must also describe things to an extent that someone else could implement. This is a difficult set of conditions to ensure throughout all the specifications added.
There is a lot of difficulty in gardening obsolete, unwanted and abandoned specifications in the Wiki.
BoF agenda and discussion
We'll have a first public session on this on the first Monday in UBZ.
SpecSpec (last edited 2010-05-30 17:13:07 by dsl-185-83-10)