launchpad helpDefining the feature you want to implement is the first step of the specification process. A spec usually goes through a fairly predictable life cycle while it is being defined. You use the "Change Status" action link on a Spec to change the definition status of the spec, and to convey to people where you currently stand.
Definition Status Values
The definition status of a specification can take one of the following values:
Discussion. The specification is a thought, or collection of thoughts, with no attention yet given to implementation strategy, dependencies or presentation/UI issues. This is the starting state of any new specification. You should leave the spec in this state as long as you are not actively spending time on shaping it up, even if you occasionally make changes.
Drafting. Use this state to indicate that the specification is actively being drafted. The spec should only be in this state if it has a drafter in place, and the spec is under regular revision. Please do not park specs in the "drafting" state indefinitely, if they are not being worked on then "Discussion" is a better definition status.
Review. This spec has been put in a reviewers queue. The drafter believes that it captures pretty much everything that is needed, but wants to get feedback from someone who will be affected by this feature. There is a specific mechanism in Blueprint to request someone to provide this kind of feedback. The reviewer will assess the clarity and comprehensiveness of the spec, and decide whether further work is needed before the spec can be considered for actual approval. This state is used when we want to get a couple of different eyeballs over a specification before it actually goes to to the chief honcho for approval.
Pending Approval. This spec has already been reviewed by relevant people, and they are happy enough with it that it can be queued for final approval. Typically, for each specification we know who is supposed to approve it, so they just monitor their personal spec approval list. Only the approver for a spec should move it over to "Approved".
Approved. The Green Light! This specification has been approved. The project team believe that it is ready to be implemented without substantial further issues being encountered. This is the final stage of the definition process, once a spec is approved the assignee should be able to get cracking without too much further debate or discussion.
In addition, there are a couple of "dead end" states where your spec can end up if it is abandoned or superseded.
Obsolete. This specification has been obsoleted. Probably, we decided not to implement it for some reason. It will not be displayed in listings by default, and people should not put any effort into implementing it or commenting further.
Superseded. The basic ideas in specification are still interesting, but for whatever reason the work of defining them has moved to a newer spec. This spec will not be displayed in most listings unless you specifically ask for ALL specs. If you use the "mark specification superseded" feature then we will remember which spec replaced this one, and display it on the spec page.
How detailed should your specification be?
The answer is "it depends". And it depends on a lot of different things.
Project guidelines and standards. Different projects set different rules about their specifications. Some projects like to have a lot of work done in advance of the implementation stage, with many people reviewing and commenting on a planned feature. In Launchpad, we tend to spend the time we have together in person mapping out features in quite some detail, so that we can be confident that each of our indeividual pieces of work will dovetail together nicely in the end. but we also recognise that sometimes the best spec is a lightweight concept document or even just a paragraph placeholder that captures the essence of an idea.
The complexity of the feature. Sometimes you just don't need a very detailed specification. If it's a quick fix, easy idea and obvious how you plan to implement it, then just drop a placeholder spec in there so you can give it a priority and keep track of implementation. It's a nice way to give people a heads-up about something new you want to do, even if you're not going to get a lot of collaboration and discussion going about it.
The collaboration required. A big factor in writing a good specification is the extent to which you really want other people to help you. If its something you will likely do all by yourself, then you probably don't want or need to map out in precise detail how you plan to do it. If, on the other hand, its something that needs to be implemented and reviewed by a bunch of different people, then a more detailed spec helps to build consensus and expectations. This is particularly true if the change you envision is pervasive, and touches the UI and the data model and the architecture of the code.
What should the specification cover?
Your general rule of thumb should be to put as much detail into the specification as you need to get a couple of other sane people to say "yeah, that looks about right". In Launchpad we ask people to describe changes in the following areas:
Data model. Be specific about what sort of RDBMS tables and fields are required to support the feature you are planning. Get outside people to review the interconnections between this new data and the existing data model, especially for things that link between subsystems owned by different people. In a more standalone app, you might spec out the data structures you intend to implement.
API's. Especially to the extent that an API will be used by OTHER developers, it really helps to have a couple of eyeballs look over the set of functions or methods and check for sanity. Most projects have coding standards, and other people will be able to point out ways for your API to be more appropriate to the rest of the codebase and the rules.
User Interface. In the case of a web app like Launchpad this means the web pages and widgets. In a desktop app you might have mockups or screenshots. And in a command line app, you would typically discuss any changes to command line options and parameters.
If you want more information you might check out the list of very best specifications we maintain here, for examples how How Its Done (TM), or check out the SpecTemplate that we use for Launchpad specs (you probably want your own spec template for your own project, but you are welcome to lift ours as a starting point). And lastly, there is a guide to writing good specs which is designed for the Ubuntu and Launchpad guys, but again might be useful for anyone else.
