launchpad helpThis page needs your help! Can you help ensure the information on this page is accurate? If so, please make the changes directly in the page. |
Introduction
This is part of the BlueprintDocumentation which explains to people how to make the most of the feature tracking in Launchpad. It is also written to help new contributors to Ubuntu and other free software projects figure out how most effectively they can get their ideas / features / wishes implemented.
What's a "good" specification?
What makes a good feature specification? The answer is "just enough information to do it right". Of course, that varies hugely depending on what the feature is, what the project is, and who you are. In general, the more people your feature implementation will touch, the more it's worth investing in the discussion of how something will work before you actually get started.
A lot of the benefit of the specification process comes from debate and discussion. Getting feedback from others makes you think about things you otherwise might not have considered - perhaps it even expands your sense of the importance of the feature you had originally conceived, or perhaps it suggests that the feature would be even more useful if it was done slightly differently.
That said, don't get bogged down in planning when the only person who needs to know is yourself. Huge design documents get more and more difficult to keep in touch with reality. Its best to pick smaller pieces of the puzzle, draw up a reasonable plan for one of them, and then implement it rather than trying to define in detail how a huge system will all hang together.
Getting outside expertise
A lot of the people who WANT features won't have the skills to IMPLEMENT them. It's common to have someone popping onto a mailing list or IRC channel and saying "Ubuntu would ROCK if it had feature XYZ!". As soon as they are asked how they would implement that, they disappear. Which is often a pity, because some of those ideas might well have legs if they could get the right set of eyeballs and brains around them.
So use Blueprint as your way of building up a small community of people who have a common interest in the feature you have conceived. You need a mix of people - some of whom have the knowledge to implement the work, and some of whom are the sorts of people who can rally support for an idea. Building community consensus is often harder than actually developing the code! And of course, it's great if you can find people with a talent for making things LOOK GOOD (artists and user interface guys) as well as WORK WELL (quality assurance, testers and end-users).
Anybody can subscribe to a feature specification, and the number and quality of subscribers can be a good indicator of the potential interest in the community for a particular feature. If you have a lot of subscribers with good credentials it won't go unnoticed by your project leaders. That said, you SHOULD NOT subscribe someone else to a specification unless they work for you or you have their permission. Subscribing someone to a feature spec means they will get email about it, and they may just not appreciate that, no matter how good your intentions.
Actually writing the specification
Here are some hints for the text of your spec:
Start with the SUMMARY of what you plan to do, not the rationale. When you start out writing the specification, you usually begin with the problem description. But everyone else who looks at that specification is going to want to start with the summary of the ACTIONS involved. So make sure you put that bit up front. A good specification starts with "This specification details the plan to... by... especially...".
Include a good rationale. Right after the summary you want to explain WHY this plan is important, and who it would benefit. You can refer to what's going on in other projects, or in the broader tech landscape, to bolster your case. It would also be good to include...
Good use cases. Often the theory of a feature plan is far less interesting than some good stories of how users will interact with the feature. Keep your use cases crisp and clean - focus just on the single new feature you are describing, not the whole framework you will have to build for it to live in!
Pictures really are worth a thousand words. For those of us who prefer short books with pictures, you will hold our attention much better with a few screenshots or mockups. Also, demonstrating that you know how to present the feature, and that you can make it slick, builds a lot of confidence in your ability to deliver.
What to cover
Your specification should touch on:
- Anything which will affect other members of the project who work on things you are not responsible for. In Launchpad, we specify database changes quite carefully, because they affect lots of people.
- The user interface, to the extent that this is important for your users. Screenshots and mockups REALLY help to give people an idea of what you want to create and how it could look and feel. In the case of a web application, mockups can be equally useful. For command line tools, its the command options and parameters that you will want to specify in advance.
- API's and data structures, especially if these are going to be exposed. For example, we take EXTRA care when we are exposing an API through XML-RPC, or publishing an API which we want outsiders to use for a protracted period of time. It gets difficult to support older API's as your application evolves, so its definitely worth putting some thought into the functionality you want to expose and how people are likely to use it.
- Changes to existing infrastructure. If you are going to be rearranging the furniture in someone else's home, best you discuss it with them first!
- New software dependencies or inclusions. In the case of Ubuntu, you probably want to be explicit about any new packages you would like to bring into the "main" component, especially if you also want new packages on the default install disks for Ubuntu, Kubuntu, Edubuntu or Xubuntu. There are established processes for doing that (main inclusion reports!) but you should also mention them in any specification. For upstreams, if your feature introduces a new dependency on a shared library, you want to be clear about that too.
- Interactions between systems. Sometimes your feature describes something that lives between other systems - for example, in Ubuntu there is a lot of work involved in the system initialisation process that affects how lots of pieces of the system interact with one another. Changes in the Ubuntu boot process (initramfs, udev, the kernel etc) have a significant potential for messing up other pieces of the system. Take extra care when defining something that touches a focal point like this, because LOTS of people will want to review your ideas, and the clearer you are, the better the suggestions they will make for you.
Your project probably has a template specification that you can use as a starting point. In the case of Launchpad and Ubuntu we have:
How do you know you are winning?
The project leaders are the people who get to say what the priority of a specification should be. They determine what the project is likely to include in its mainline codebase and what it won't. At the same time, there's plenty of room for dissent and diversity of opinion - some of the very best features are often developed on the side by a small group of people who want them, and then they are incorporated in the mainline only once the project leaders can actually see and test them.
So don't be discouraged if your specification gets a "low" or "not" priority - that just means that the project leaders themselves aren't going to jump onto the problem. It does not mean you shouldn't bother to continue.
Getting a higher priority from the project leaders does generally mean that you might get direct help from one of the core developers or members, so its worth canvassing for support for your feature idea. But don't overdo it - if people aren't excited about your feature, they won't get excited unless you improve the way you are describing it, and that means putting more work into your specification.
