Merge lp:~jml/launchpad/vision-doc-split into lp:launchpad

[Jonathan Lange]

I was looking over the vision document and noticed that it was a bit long. I thought that it might be a good idea to split it into a "strategy" document which talks about "why and who for", and a "scope" document that talks about "what". This branch does that.

It also cleans up some rST issues and wording issues and renames the 'vision' file to 'strategy'.

To look over the docs, download the branch, run 'make doc', and then browse to 'doc/_build/html/index.html'. Very much open to feedback on the broader area rather than simply the changes in this branch.

[Jonathan Lange (jml)]

Oh, should point out that the images look tiny in Chrome, but are proper sized in Firefox.

[Gavin Panella (allenap)]

This looks good, but I haven't time this evening to give it a thorough read through. I'll do that in the morning. In the meantime I've left the ~launchpad review slot open.

[Martin Pool (mbp)]

+1

It would be nice if there was a standard url for them. Or perhaps they should move onto the dev wiki or the blog.

[Matthew Revell (matthew.revell)]

Thanks, it was nice to have an excuse to spend some time reading this again.

I think the split works well.

I should probably know this but why is this published at "http://lpqateam.canonical.com/doc/"? Presumably because we had that subdomain easily available to us.

Also, I'd second Martin's call and suggest we make the link to this, from the dev wiki, more prominent. I need to spend some time fixing up the dev wiki in general.

I noticed something in the scope doc:

"Many other forges exist to become more successful." I understand why you've used this wording and I feel that I am nitpicking here but I think we want Launchpad to become more successful, it's just that we have a different definition of success.

review: Approve

[Jonathan Lange (jml)]

On Fri, Apr 1, 2011 at 10:09 AM, Matthew Revell
<email address hidden> wrote:
> Review: Approve
> Thanks, it was nice to have an excuse to spend some time reading this again.
>
> I think the split works well.
>
> I should probably know this but why is this published at "http://lpqateam.canonical.com/doc/"? Presumably because we had that subdomain easily available to us.
>

Exactly. When we are being blocked on RTs for things that actually
affect users and developers, I figured I'd take what I could get.

> Also, I'd second Martin's call and suggest we make the link to this, from the dev wiki, more prominent. I need to spend some time fixing up the dev wiki in general.
>

As long as it's a link. I think having these on the wiki will lead to
them being more poorly maintained.

> I noticed something in the scope doc:
>
> "Many other forges exist to become more successful." I understand why you've used this wording and I feel that I am nitpicking here but I think we want Launchpad to become more successful, it's just that we have a different definition of success.
>

Fair call. Changed to "Many other forges define their success by how
many users they have."

jml

[Gavin Panella (allenap)]

Like Matt, I think it would be good to make this more visible, more public. The audience of this is not the same as the audience of the code in the tree, so perhaps it's not in the perfect location, but perfect is the enemy of good.

+1

review: Approve

=== modified file 'doc/index.txt'
--- doc/index.txt	2011-02-16 13:08:25 +0000
+++ doc/index.txt	2011-04-01 10:09:24 +0000
@@ -17,7 +17,8 @@
    :maxdepth: 1
 
    readme
-   vision
+   strategy
+   scope
    values
 
 Technical

=== added file 'doc/scope.txt'
--- doc/scope.txt	1970-01-01 00:00:00 +0000
+++ doc/scope.txt	2011-04-01 10:09:24 +0000
@@ -0,0 +1,341 @@
+==================
+What is Launchpad?
+==================
+
+Launchpad is a complete system for gathering changes from different types of
+sources and collaboratively organizing them into packaged software for the end
+user, delivered as part of an operating system that can be downloaded or that
+comes already installed on purchased hardware.
+
+If you start by thinking of Launchpad as a traditional software “forge” – a
+web service that provides bug tracking, code hosting and other related
+services – then you are not too far off understanding what Launchpad is.
+However, Launchpad has many distinctive traits that combine to put it into an
+entirely different category of software.
+
+But at its core, it is best to think of Launchpad as a service that meshes
+together two important networks:
+
+1. Networks of people making software
+2. The network of dependencies between software
+
+But first, a story.
+
+
+The Story of a Bug
+==================
+
+*Arnold* writes software for a living, and he runs Ubuntu on his desktop. He
+wishes he could contribute to open source, but he doesn’t have much spare
+time, and when he gets home from his job the last thing he wants to do is
+program. However, the spirit of willingness is there.
+
+One day, Arnold notices that Tomboy loses his formatting if he alt-tabs at the
+wrong time. Arnold knows that a well-filed bug report is a thing of beauty to
+most programmers, so he decides to spend a few moments to file a bug against
+Tomboy.
+
+Rather than search the net to find where Tomboy tracks its bugs, Arnold uses
+Ubuntu’s built-in bug filing mechanism. It asks him a bunch of questions,
+invites Arnold to write his bug report and then files the bug on Launchpad
+against the Tomboy package in Ubuntu.
+
+*Becca* has been dabbling in Ubuntu contribution for a while, mostly by
+helping new users solve their problems or turn them into good bug reports. She
+notices Arnold’s bug, sees that it’s well written and thinks that it would be
+easy enough to test against trunk. She opens up the Tomboy source package in
+Ubuntu and sees that there is a known-good daily build of Tomboy’s trunk
+hosted in a trusted user archive. Becca installs Tomboy from this archive and
+tests to see if the bug is still there in the latest version of the code. It
+is. Becca sees this, opens up the original bug report and clicks a button to
+forward the bug to the upstream bug tracker.
+
+*Carlos* is one of the Tomboy developers. He sees the bug in the tracker, sees
+that it has been tested against trunk, realizes that it’s an annoying bug
+that’s easy to fix and decides to fix it. He does the fix, applies it to the
+Tomboy trunk and marks the bug as fixed.
+
+At this point, both Arnold and Becca are notified that the bug is fixed in
+Tomboy trunk, and that they can try a version of Tomboy that has the fix by
+using the known-good daily build archive for Tomboy. They are warned that this
+is dangerous and may cause data loss, but they are also told how they can try
+the bug fix for free using a cloud-based Ubuntu desktop. They both try the
+bug, see that it’s fixed, and are happy, albeit a little impatient for the fix
+to be actually released and part of stock Ubuntu.
+
+Meanwhile, *Dalia* is an Ubuntu developer who takes a special interest in
+desktop productivity applications like Tomboy. She checks on the Ubuntu source
+package for Tomboy from time to time. The last time she checked, she saw that
+quite a few bugs have been fixed in trunk but not yet released. Since she
+knows the Tomboy release manager from long hours of IRC chat, she contacts him
+and gently suggests that he do a release.
+
+*Edmund*, the Tomboy release manager, takes Dalia’s hint well and realizes
+that a release is way overdue. He makes a release of Tomboy following his
+normal procedure.
+
+Launchpad detects that Tomboy has a new, official release and alerts
+interested distribution maintainers that the release has been made and now
+would be a good time to package a new version. Dalia packages up a new
+version, requests that an Ubuntu core developer sponsor the change and then
+waits for the new version to be uploaded. Dalia also uploads the fixed version
+to one of her personal archives so that others can easily get it without
+waiting for the next release of Ubuntu.
+
+*Fiona* the Ubuntu core developer sees Dalia’s patch in the sponsorship queue
+on Launchpad, notes that it’s all good and then uploads the patch to the
+official Ubuntu archive. (Fiona might also choose to upload the patch to
+Debian).
+
+Launchpad sees that this upload fixes a number of bugs, including the one
+originally filed by Arnold, and automatically includes those bugs in the list
+of bugs that will be fixed by the next release of Ubuntu.
+
+Two months later, the next release of Ubuntu is actually released. Arnold
+upgrades on release day, and tries out Tomboy to see if his bug was really,
+actually fixed. It is, and all is right with the world.
+
+
+
+
+Distinctive traits
+==================
+
+Launchpad is different from other "forges" in a few important ways:
+
+
+Cross-project collaboration
+---------------------------
+
+No project lives in isolation.  Each project is part of an ecosystem of
+software.  Projects must be able to interact with each other, share bugs,
+teams, goals and code with each other.
+
+.. image:: images/cross-project-collab.svg
+
+Launchpad takes every chance it gets to show the connections between projects
+and to bring the opportunities created by those connections to light.
+
+By encompassing the entire process, all the way to operating system delivery,
+Launchpad can provide a unique service: enable each contributor to focus on
+the work they care about, while giving them an ambient awareness of how their
+work fits into a larger picture, and providing a path by which they can
+participate in other parts of that picture when they feel the need.
+
+
+Front-end to open source
+------------------------
+
+Launchpad aims to be a front-end to open source.  Whether or not a project
+chooses to host on Launchpad, opportunistic developers can use Launchpad to
+navigate bugs, get code and send patches.  Likewise, we aim to present a
+uniform interface to the projects we have.
+
+
+Centralized service
+-------------------
+
+Because Launchpad emphasises cross-project collaboration, and because
+Launchpad aims to be a front-end to all of open source, it necessarily has to
+be a centralized service rather than a product that users deploy on their own
+servers.
+
+
+Networks of collaborators
+-------------------------
+
+Launchpad understands that much of the human interaction around open source is
+not primarily social, but rather collaborative: many people working together
+in different ways toward the same goals.
+
+As such, Launchpad highlights actions and opportunities rather than
+conversations and status. It answers questions like, “what can I do for you?”,
+“who could help me do this?”, “who is waiting on me in order to get their
+thing done?”, “can I rely on the advice offered by this person?” and so forth.
+
+
+Distributions are projects too
+------------------------------
+
+Launchpad hosts Linux distributions in much the same way as it hosts projects,
+allowing for developers to feel at home when interacting with distributions.
+
+
+Gated development
+-----------------
+
+Sometimes, secrets are necessary.  Launchpad understands that sometimes
+development needs to be done privately, and the results only later shared with
+the world.  Security fixes, OEM development for new hardware, proprietary
+services with open source clients are all examples of these.
+
+
+Hardware matters
+----------------
+
+Many software developers like to pretend that hardware does not really
+exist. When people distribute software as part of an operating system, they
+don't have the luxury of forgetting. Launchpad understands that developers
+often need to acknowledge and work around differences thrown up by hardware.
+
+
+We don't care if you use Launchpad, sort of
+-------------------------------------------
+
+Many other forges define their success by how many users they have.  Although
+we love our users and welcome every new user, Launchpad does not judge its
+success by the number of users.  If one project wishes to host its development
+on another platform, Launchpad acts as a front-end to that platform.
+
+
+One project, many communities
+-----------------------------
+
+Any given project can have many distinct communities interested in it.  These
+communities have different interests and different motivations, but all work
+in the same project space so that they can easily benefit from each others'
+efforts.
+
+
+Scope
+=====
+
+Launchpad has many major components. These can be broken up into four major
+areas of functionality:
+
+1. where work is done; developers interact with other developers
+2. where plans are made and reviewed; expert users interact with expert users
+   and developers
+3. where projects engage with their communities; developers interact with end
+   users and other developers, and vice-versa
+4. major supporting features
+
+.. image:: images/scope.svg
+
+Work
+----
+
+At the core of every software project is the actual code that makes up that
+project. Here “code” is a broad term that also includes the project’s
+documentation, the translatable and translated strings that make up its user
+interface, the packaging and integration scripts required to get the software
+installed on end user’s systems and so forth.
+
+Launchpad is built to be able to take contributions from anybody, regardless
+of how involved they are in a project. For packages, translations and code
+proper we provide mechanisms to allow people to review changes from others and
+then merge them into the official parts of the project.
+
+Launchpad pulls in changes that happen in the upstreams and downstreams of a
+project, whether those changes are patches to code, new translations or
+packaging updates. It makes contributors to a project aware of the work that’s
+going on upstream and downstream and helps them take advantage of that work.
+
+And, of course, all work is for nothing if it does not get to the people who
+might want to actually use its results. As such, project maintainers can
+publish released versions of their code, any contributor can publish Ubuntu
+packages to unofficial archives or even set up Launchpad to automatically
+build and publish packages of latest snapshots of code.
+
+
+Plans
+-----
+
+People who are interested in doing something great will need to coordinate
+their work, keep track of the defects in the things they have already done and
+describe the things that they aren't doing yet but wish they could.
+
+Every software product in the world has bugs. For some projects, the rate of
+incoming bugs is fairly low, and each bug can expect to receive some attention
+from a core developer.  For other projects, the rate of new bugs filed is so
+high that the core development team can never hope to keep up with it.
+Launchpad supports both kinds of projects.
+
+If every software product has bugs, every software user has great ideas about
+how a product can be improved. Project maintainers need to get at these ideas,
+evaluate them, and develop them into workable concepts.
+
+Often, a problem is so tricky that those concerned need to have a detailed,
+managed discussion about what exactly the problem is.  At other times, the
+problem is easy enough to define, but there are so many solutions with
+difficult trade-offs or difficult implementations that it is better to talk
+about them and plan them out before proceeding with any of them. Launchpad
+acknowledges that this can happen on any project, and that becoming clear on a
+problem or becoming clear on the “best” solution can be helped a great deal
+using tools.
+
+Crucially, all of these different types of “plans” – bugs, specifications,
+blueprints, ideas – can span more than one code base and more than one
+conceptual project. These plans need to be drafted, discussed, clarified and
+reviewed before work starts, monitored, evaluated and changed as work
+progresses, and then the results of that work need to be checked against the
+plan when the work is finished.
+
+
+Community
+---------
+
+Not everything that’s done on a project is work toward a particular outcome,
+or plans for how to get there. Every project needs to have some things that
+are more general and stable.
+
+Projects need to be able to present themselves to the world, confident in
+their identity and communicating exactly what they are about. Project
+maintainers need to be able to announce important news, such as releases,
+license changes or new practices. Contributors need to get a sense of who is
+working on which parts of the project. Users need to be able to ask questions,
+get support and give feedback.
+
+Contributors also need to share documentation about the project and how the
+project runs. They need to be able to discuss general topics about the
+project.
+
+Launchpad supports all of these things, and also makes it clear how any
+project fits into the broader ecosystem of projects. It shows which projects
+are upstreams or downstreams, which projects are affiliated with other
+projects, which projects share contributors with other projects and so forth.
+
+
+Supporting features
+-------------------
+
+Launchpad has many major areas of functionality that are best considered as
+“supporting features”: APIs, migration services, privacy, the mail UI,
+synchronizing with external systems.
+
+
+New World
+=========
+
+When Launchpad is really doing all of these things and doing them well, the
+world of open source software will be significantly changed.
+
+Patches will no longer lie decaying in someone else’s bug tracker, waiting to
+be noticed. Instead, they will all be synced into a central code review system
+and queued for review and approval.
+
+Instead of a distribution tracking one set of bugs and upstream projects
+tracking their own set of sometimes duplicated bugs, both upstream and
+downstream developers can seamlessly accesses both sets of bugs.
+
+
+Glossary
+========
+
+Upstream
+  A software project itself, as opposed to the packaged version of a software
+  project that is included in a distribution. Note, can also be used as a
+  relative term, e.g. “Debian is upstream of Ubuntu”.
+
+Downstream
+  The opposite of an upstream. Can be used to refer either to a packaged
+  version of a specific software project, or the entire distribution where
+  that package occurs.
+
+
+References
+==========
+
+* :doc:`strategy`
+* :doc:`values`
+* `Feature checklist <https://dev.launchpad.net/FeatureChecklist>`_

=== renamed file 'doc/vision.txt' => 'doc/strategy.txt'
--- doc/vision.txt	2011-01-16 19:49:31 +0000
+++ doc/strategy.txt	2011-04-01 10:09:24 +0000
@@ -1,6 +1,6 @@
-=============================
-Launchpad: Strategy and scope
-=============================
+==================
+Launchpad Strategy
+==================
 
 *We want to make Ubuntu the world’s best operating system. To do this, we need
 to give Canonical an edge in productivity over and above other Linux vendors
@@ -17,16 +17,15 @@
 This document tries to answer two big questions:
 
 1. *why* are we making Launchpad?
-1. *what* is Launchpad supposed to be?
+2. *who* is Launchpad for?
+
+This is not our strategy for the year or the scope of Launchpad development
+for the next six months.  Rather, it is our answer to these fundamental
+questions.
 
 When you are finished reading this document, you should know what problems we
-want to solve, what we hope to gain from solving these problems, how we decide
-whether something is in scope or not and how we know if Launchpad is doing
-well.
-
-This is not our strategy for the year or our scope of Launchpad development
-for the next six months.  Rather, it is our answer to the fundamental
-questions: what is Launchpad and why is Canonical investing in it?.
+want to solve, what we hope to gain from solving these problems and how we
+know if Launchpad is doing well.
 
 
 Audience
@@ -37,8 +36,8 @@
 developers of Launchpad, whether they are Canonical employees or not.
 
 
-Strategy -- Why are we doing this?
-==================================
+Why are we making Launchpad?
+============================
 
 The world we live in
 --------------------
@@ -189,338 +188,9 @@
 than many open source and even proprietary projects.
 
 
-What is Launchpad?
-==================
-
-Launchpad is a complete system for gathering changes from different types of
-sources and collaboratively organizing them into packaged software for the end
-user, delivered as part of an operating system that can be downloaded or that
-comes already installed on purchased hardware.
-
-If you start by thinking of Launchpad as a traditional software “forge” – a
-web service that provides bug tracking, code hosting and other related
-services – then you are not too far off understanding what Launchpad is.
-However, Launchpad has many distinctive traits that combine to put it into an
-entirely different category of software.
-
-But at its core, it is best to think of Launchpad as a service that meshes
-together two important networks:
-
-1. Networks of people making software
-2. The network of dependencies between software.
-
-
-Distinctive traits
-------------------
-
-Launchpad is different from other "forges" in a few important ways:
-
-
-Cross-project collaboration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-No project lives in isolation.  Each project is part of an ecosystem of
-software.  Projects must be able to interact with each other, share bugs,
-teams, goals and code with each other.
-
-.. image:: images/cross-project-collab.svg
-
-Launchpad takes every chance it gets to show the connections between projects
-and to bring the opportunities created by those connections to light.
-
-By encompassing the entire process, all the way to operating system delivery,
-Launchpad can provide a unique service: enable each contributor to focus on
-the work they care about, while giving them an ambient awareness of how their
-work fits into a larger picture, and providing a path by which they can
-participate in other parts of that picture when they feel the need.
-
-
-Front-end to open source
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-Launchpad aims to be a front-end to open source.  Whether or not a project
-chooses to host on Launchpad, opportunistic developers can use Launchpad to
-navigate bugs, get code and send patches.  Likewise, we aim to present a
-uniform interface to the projects we have.
-
-
-Centralized service
-~~~~~~~~~~~~~~~~~~~
-
-Because Launchpad emphasises cross-project collaboration, and because
-Launchpad aims to be a front-end to all of open source, it necessarily has to
-be a centralized service rather than a product that users deploy on their own
-servers.
-
-
-Networks of collaborators
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Launchpad understands that much of the human interaction around open source is
-not primarily social, but rather collaborative: many people working together
-in different ways toward the same goals.
-
-As such, Launchpad highlights actions and opportunities rather than
-conversations and status. It answers questions like, “what can I do for you?”,
-“who could help me do this?”, “who is waiting on me in order to get their
-thing done?”, “can I rely on the advice offered by this person?” and so forth.
-
-
-Distributions are projects too
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Launchpad hosts Linux distributions in much the same way as it hosts projects,
-allowing for developers to feel at home when interacting with distributions.
-
-
-Gated development
-~~~~~~~~~~~~~~~~~
-
-Sometimes, secrets are necessary.  Launchpad understands that sometimes
-development needs to be done privately, and the results only later shared with
-the world.  Security fixes, OEM development for new hardware, proprietary
-services with open source clients are all examples of these.
-
-
-Hardware matters
-~~~~~~~~~~~~~~~~
-
-Many software developers like to pretend that hardware does not really
-exist. When people distribute software as part of an operating system, they
-don't have the luxury of forgetting. Launchpad understands that developers
-often need to acknowledge and work around differences thrown up by hardware.
-
-
-We don't care if you use Launchpad, sort of
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Many other forges exist to become more successful.  Although we love our users
-and welcome every new user, Launchpad does not judge its success by the number
-of users.  If one project wishes to host its development on another platform,
-Launchpad acts as a front-end to that platform.
-
-
-One project, many communities
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Any given project can have many distinct communities interested in it.  These
-communities have different interests and different motivations, but all work
-in the same project space so that they can easily benefit from each others'
-efforts.
-
-
-Scope
-=====
-
-Launchpad has many major components. These can be broken up into four major
-areas of functionality:
-
-1. where work is done; developers interact with other developers
-2. where plans are made and reviewed; expert users interact with expert users
-   and developers
-3. where projects engage with their communities; developers interact with end
-   users and other developers, and vice-versa
-4. major supporting features
-
-.. image:: images/scope.svg
-
-Work
-----
-
-At the core of every software project is the actual code that makes up that
-project. Here “code” is a broad term that also includes the project’s
-documentation, the translatable and translated strings that make up its user
-interface, the packaging and integration scripts required to get the software
-installed on end user’s systems and so forth.
-
-Launchpad is built to be able to take contributions from anybody, regardless
-of how involved they are in a project. For packages, translations and code
-proper we provide mechanisms to allow people to review changes from others and
-then merge them into the official parts of the project.
-
-Launchpad pulls in changes that happen in the upstreams and downstreams of a
-project, whether those changes are patches to code, new translations or
-packaging updates. It makes contributors to a project aware of the work that’s
-going on upstream and downstream and helps them take advantage of that work.
-
-And, of course, all work is for nothing if it does not get to the people who
-might want to actually use its results. As such, project maintainers can
-publish released versions of their code, any contributor can publish Ubuntu
-packages to unofficial archives or even set up Launchpad to automatically
-build and publish packages of latest snapshots of code.
-
-
-Plans
------
-
-People who are interested in doing something great will need to coordinate
-their work, keep track of the defects in the things they have already done and
-describe the things that they aren't doing yet but wish they could.
-
-Every software product in the world has bugs. For some projects, the rate of
-incoming bugs is fairly low, and each bug can expect to receive some attention
-from a core developer.  For other projects, the rate of new bugs filed is so
-high that the core development team can never hope to keep up with it.
-Launchpad supports both kinds of projects.
-
-If every software product has bugs, every software user has great ideas about
-how a product can be improved. Project maintainers need to get at these ideas,
-evaluate them, and develop them into workable concepts.
-
-Often, a problem is so tricky that those concerned need to have a detailed,
-managed discussion about what exactly the problem is.  At other times, the
-problem is easy enough to define, but there are so many solutions with
-difficult trade-offs or difficult implementations that it is better to talk
-about them and plan them out before proceeding with any of them. Launchpad
-acknowledges that this can happen on any project, and that becoming clear on a
-problem or becoming clear on the “best” solution can be helped a great deal
-using tools.
-
-Crucially, all of these different types of “plans” – bugs, specifications,
-blueprints, ideas – can span more than one code base and more than one
-conceptual project. These plans need to be drafted, discussed, clarified and
-reviewed before work starts, monitored, evaluated and changed as work
-progresses, and then the results of that work need to be checked against the
-plan when the work is finished.
-
-
-Community
----------
-
-Not everything that’s done on a project is work toward a particular outcome,
-or plans for how to get there. Every project needs to have some things that
-are more general and stable.
-
-Projects need to be able to present themselves to the world, confident in
-their identity and communicating exactly what they are about. Project
-maintainers need to be able to announce important news, such as releases,
-license changes or new practices. Contributors need to get a sense of who is
-working on which parts of the project. Users need to be able to ask questions,
-get support and give feedback.
-
-Contributors also need to share documentation about the project and how the
-project runs. They need to be able to discuss general topics about the
-project.
-
-Launchpad supports all of these things, and also makes it clear how any
-project fits into the broader ecosystem of projects. It shows which projects
-are upstreams or downstreams, which projects are affiliated with other
-projects, which projects share contributors with other projects and so forth.
-
-
-Supporting features
--------------------
-
-Launchpad has many major areas of functionality that are best considered as
-“supporting features”: APIs, migration services, privacy, the mail UI,
-synchronizing with external systems.
-
-
-New World
-=========
-
-When Launchpad is really doing all of these things and doing them well, the
-world of open source software will be significantly changed.
-
-Patches will no longer lie decaying in someone else’s bug tracker, waiting to
-be noticed. Instead, they will all be synced into a central code review system
-and queued for review and approval.
-
-Instead of a distribution tracking one set of bugs and upstream projects
-tracking their own set of sometimes duplicated bugs, both upstream and
-downstream developers can seamlessly accesses both sets of bugs.
-
-
-The story of a bug
-------------------
-
-*Arnold* writes software for a living, and he runs Ubuntu on his desktop. He
-wishes he could contribute to open source, but he doesn’t have much spare
-time, and when he gets home from his job the last thing he wants to do is
-program. However, the spirit of willingness is there.
-
-One day, Arnold notices that Tomboy loses his formatting if he alt-tabs at the
-wrong time. Arnold knows that a well-filed bug report is a thing of beauty to
-most programmers, so he decides to spend a few moments to file a bug against
-Tomboy.
-
-Rather than search the net to find where Tomboy tracks its bugs, Arnold uses
-Ubuntu’s built-in bug filing mechanism. It asks him a bunch of questions,
-invites Arnold to write his bug report and then files the bug on Launchpad
-against the Tomboy package in Ubuntu.
-
-*Becca* has been dabbling in Ubuntu contribution for a while, mostly by
-helping new users solve their problems or turn them into good bug reports. She
-notices Arnold’s bug, sees that it’s well written and thinks that it would be
-easy enough to test against trunk. She opens up the Tomboy source package in
-Ubuntu and sees that there is a known-good daily build of Tomboy’s trunk
-hosted in a trusted user archive. Becca installs Tomboy from this archive and
-tests to see if the bug is still there in the latest version of the code. It
-is. Becca sees this, opens up the original bug report and clicks a button to
-forward the bug to the upstream bug tracker.
-
-*Carlos* is one of the Tomboy developers. He sees the bug in the tracker, sees
-that it has been tested against trunk, realizes that it’s an annoying bug
-that’s easy to fix and decides to fix it. He does the fix, applies it to the
-Tomboy trunk and marks the bug as fixed.
-
-At this point, both Arnold and Becca are notified that the bug is fixed in
-Tomboy trunk, and that they can try a version of Tomboy that has the fix by
-using the known-good daily build archive for Tomboy. They are warned that this
-is dangerous and may cause data loss, but they are also told how they can try
-the bug fix for free using a cloud-based Ubuntu desktop. They both try the
-bug, see that it’s fixed, and are happy, albeit a little impatient for the fix
-to be actually released and part of stock Ubuntu.
-
-Meanwhile, *Dalia* is an Ubuntu developer who takes a special interest in
-desktop productivity applications like Tomboy. She checks on the Ubuntu source
-package for Tomboy from time to time. The last time she checked, she saw that
-quite a few bugs have been fixed in trunk but not yet released. Since she
-knows the Tomboy release manager from long hours of IRC chat, she contacts him
-and gently suggests that he do a release.
-
-*Edmund*, the Tomboy release manager, takes Dalia’s hint well and realizes
-that a release is way overdue. He makes a release of Tomboy following his
-normal procedure.
-
-Launchpad detects that Tomboy has a new, official release and alerts
-interested distribution maintainers that the release has been made and now
-would be a good time to package a new version. Dalia packages up a new
-version, requests that an Ubuntu core developer sponsor the change and then
-waits for the new version to be uploaded. Dalia also uploads the fixed version
-to one of her personal archives so that others can easily get it without
-waiting for the next release of Ubuntu.
-
-*Fiona* the Ubuntu core developer sees Dalia’s patch in the sponsorship queue
-on Launchpad, notes that it’s all good and then uploads the patch to the
-official Ubuntu archive. (Fiona might also choose to upload the patch to
-Debian).
-
-Launchpad sees that this upload fixes a number of bugs, including the one
-originally filed by Arnold, and automatically includes those bugs in the list
-of bugs that will be fixed by the next release of Ubuntu.
-
-Two months later, the next release of Ubuntu is actually released. Arnold
-upgrades on release day, and tries out Tomboy to see if his bug was really,
-actually fixed. It is, and all is right with the world.
-
-
-Glossary
-========
-
-Upstream
-  A software project itself, as opposed to the packaged version of a software
-  project that is included in a distribution. Note, can also be used as a
-  relative term, e.g. “Debian is upstream of Ubuntu”.
-
-Downstream
-  The opposite of an upstream. Can be used to refer either to a packaged
-  version of a specific software project, or the entire distribution where
-  that package occurs.
-
-
 References
 ==========
 
-* `Product values <values.txt>`_
+* :doc:`scope`
+* :doc:`values`
 * `Feature checklist <https://dev.launchpad.net/FeatureChecklist>`_

=== modified file 'doc/values.txt'
--- doc/values.txt	2011-01-14 17:54:43 +0000
+++ doc/values.txt	2011-04-01 10:09:24 +0000
@@ -1,23 +1,24 @@
-=================
-Launchpad: Values
-=================
+================
+Launchpad Values
+================
 
 Whenever we are thinking about what Launchpad should be, or how we should
 implement a change, or whether something is a good idea or not, we have
-recourse to two distinct sets of guidelines.
-
-The first is the Launchpad Vision <vision>.  It can help us answer questions
-such as, "Is this in scope?", "How does this help Launchpad meet its goals?".
-It tries to sort out the 'matter' of Launchpad.
-
-The second is this document, the Launchpad Values.  It tries to address the
+recourse to three distinct sets of guidelines.
+
+The first is :doc:`strategy`, which reminds us why we are making Launchpad and
+helps us answer questions such as "How does this help Launchpad meet its
+goals?".  The second is :doc:`scope`, which helps us answer questions like "Is
+this in scope?".  Together, they sort out the 'matter' of Launchpad.
+
+The third is this document, the Launchpad Values.  It tries to address the
 'manner' of Launchpad.  It, perhaps, will not answer specific questions for
 you.  Rather, it will rule out certain options and decisions before they are
 even considered.
 
-Like the Vision, this document is living: it should be changed and improved as
-we learn more about how to make Launchpad.  It is also aspirational: not all
-of Launchpad lives up to these values.
+Like the :doc:`strategy`, this document is living: it should be changed and
+improved as we learn more about how to make Launchpad.  It is also
+aspirational: not all of Launchpad lives up to these values.
 
 
 Better tools help
@@ -162,3 +163,10 @@
 Likewise, importing translations from an upstream is great, but it becomes
 much, much better when those translations can be improved in Launchpad and
 then sent back to the upstream.
+
+
+References
+==========
+
+* :doc:`strategy`
+* :doc:`scope`