QEMU PRIP: 0
- As a project user I will be able to start up the widgetizer with
- As a QEMU developer I can summarize all of the discussion about an improvement such that future developers and users can find the results in one document.
A prpl Improvement Proposal, or PRIP, is a document that defines a process or feature improvement in prpl QEMU. Not every change to prpl QEMU must have a PRIP. Bug fixes, for example, are often sufficiently defined in the issue tracker. For everything else the PRIP process is intended to be lightweight process that provides value for developers today and tomorrow by recording the data that went into a decision and providing "institutional memory" for everyone working on the prpl QEMU.
Proposing a change with a PRIP
The following list describes one approach for improving prpl QEMU using a PRIP:
- Have an idea for improving prpl QEMU.
- Break it down, if necessary, to discrete ideas. We don't want to lose the big picture but breaking down big ideas helps ensure you've thought through all the steps and helps others better understand your proposal.
- Open a feature request on the prpl QEMU issue tracker. Provide enough detail about what the improvement does and how it makes prpl QEMU better; that allows the triage team and attendees to offer feedback and, if all goes well, schedule the feature in an appropriate release.
- Draft your PRIP. Get the ideas "down on paper." Add a PRIP to the prpl QEMU wiki (must simplify this?).
- Get public feedback. You have many options for feedback: E-mail the prpl QEMU mailing list describing the proposed change. Blog posts. Tweets. Discussions at online meetings.
- Capture the feedback. Use the feedback to improve your PRIP. Add useful suggestions. Address weaknesses. List alternatives. Consider what it means if you're getting lots of negative feedback. (But don't let the haters get to you.)
- Update your PRIP. Complete all the sections of the PRIP. Keep discussing on the mailing list. When you're done, send the feature request back for triage to get final approval.
That's not a hard set of rules; nor do you have to do them in that order serially. You could finish coding your change before writing one word in a PRIP, for example. The risk in doing so is that you miss out on feedback when you could incorporate it at relatively low cost -- that is, relatively little rework. It's better to overcommunicate and overdiscuss.
Creating a prpl Improvement Proposal
The feature request number from the issue tracker also serves as the unique PRIP identifier. Using the same identifier lets us use the issue tracker to schedule (and possibly re-schedule) the feature request with all the other bugs going into a release. It is up to you to ensure that you've entered the correct number as the PRIP identifier.
// needs to describe how to create
PRIP User Stories
The PRIP starts with user stories. Follow the standard user story format "As a [role], I can [accomplish task thanks to proposal] such that [benefit from proposal]." There are a couple standard roles in the QEMU:
- Add some examples
Ideally, there is more than one user story.
The proposal section of the PRIP is a fairly freeform description of the feature or process improvement. Provide the motivation for the proposal. Describe how the proposal works. List examples, particularly source code, that demonstrates how the improvement will be used. Basically, provide the bulk of the detail about the PRIP here.
As issues with the proposal come to mind or are raised by reviewers, capture them in the considerations section of the PRIP. As appropriate, explain the trade offs of the proposed design and why a particular decision was made. This section may provide the most value for developers and users that follow later so do not be afraid to list everything that comes to mind. Rare is it that a proposal doesn't have some negatives to consider.
Like the code of the prpl QEMU, PRIPs are designed to be living documents. So do not be afraid to "check in early and often". Edit the document anytime you feel there is something available to . The PRIP update pull requests will be accepted like any code submission, with a very low review bar (essentially, as long as the update is coherent we'll integrate it for discussion).
PRIPs documents can be discussed anywhere (mailing list, online meetings, twitter, etc) but everyone is encouraged to contribute their ideas to the proposal by editing the document or working with the author to update the document.
The PRIP process is designed to add value with as little overhead as possible. Of course, it takes effort to write down how a feature should work. But often the process of writing down how to solve a problem, issues are uncovered that were not initially considered.
More than anything capturing the process adds tremendous value. So, while it takes a bit more time up front, we think the PRIPs will add a lot of value over the long term.
Finally, this is not a college writing assignment. Use as many words as necessary to capture the idea. No need to write a book. Also, feel free to enlist others to help you write the document. Start with a rough draft and have someone help flesh out the missing details.
The content of this page is licensed under the Microsoft Reciprocal License
The content of this page is a derivative work of , Copyright (c) 2004, Outercurve Foundation.