launchpad-dev team mailing list archive

[Michael Hudson <michael.hudson@xxxxxxxxxxxxx>]

On 31/03/10 22:59, Bjorn Tillenius wrote:
> Hi guys,
>
> so, it's time for the Technical Architect team to tackle its first task.
> Create the Launchpad Architectural Vision.

I agree with others that "Overview" seems like a better word here.

> First of all, what is it? It's aimed to be documents that describe the
> different parts of Launchpad. It will explain how Launchpad works, which
> moving parts are involved, and how it will fit together. It will also
> explain the various sub-systems, and explain how to do various things in
> Launchpad code. For example, how do I send and receive e-mail? How do I
> add an html page? How do I write a script? Etc.
>
> An important goal of the Vision is to avoid people doing duplicate work,
> so it should document that canonical way of doing various things in
> Launchpad. If you implement a new feature, and for example don't know
> how the implementation should look like, the Vision should be the place
> to look, to see what existing code you can re-use. That's why I want to
> focus on things that are shared (or supposed to be shared) across
> applications to start with.
>
> I need your help, though! It's a lot of work, and some of you have a lot
> of expertise of certain areas of Launchpad. I need help figuring out
> what should be included in the Vision. I also need volunteers describing
> the different parts. For example, someone from the Code team would be a
> good candidate writing about the job system. Although, not necessarily.
> If you're interested in how a certain part works, trying to document it
> is a great way of learning! Also, you don't have to volunteer yourself,
> finding other volunteers is also acceptable :)
>
> These are the things I thought of so far that should be included:
>
>      * Overview of Launchpad and its moving parts
>      * job system
>      * e-mail (sending/receiving)
>      * Database garbage collection (garbo)
>      * expose API methods/attributes
>      * Web app
>          * Browser views
>          * TAL formatters
>      * Librarian
>      * Comments
>      * DB Schema
>      * LaunchpadScript
>          * LaunchpadCronScript
>      * Security policy
>      * SSH server

While there is only one SSH server now, there will hopefully be two soon 
(a poppy replacement) so here I guess we should be clear and say "the 
codehosting ssh server".

>      * Code layout (what's in lp.code/lp.services/lp.registry/etc.)
>      * Testing
>          * Where to place tests
>          * How to write tests
>          * Layers
>
> Anything missing?

Some bits of codehosting:

 * the puller
 * the scanner
 * the virtual file system used to access branches
 * code imports

Also Soyuz seems to be missing entirely...

> So, how to go about writing the documentation? Well, to start with, you
> can check out lp:~bjornt/launchpad/architect-vision. In there, there is
> an 'architect-vision' dir in the root. If you install python-sphinx and
> run 'make html' in there, you get html files in .build/html that you can
> view in a browser.

Cool, publishing the documentation IMHO has a much greater chance of 
making it useful :)

> A couple of things to think about:
>
>      * I don't want to give too many guidelines how to write. Let's do a
>        set-based design, look at how different people format their
>        documentations, and consilidate later
>
>      * Please use doctests! It's important that the documentation is
>        up to date. Doctests is a great way of doing this. The doctests
>        shouldn't aim to test the feature, though. We have other tests for
>        this. The aim for the doctest is to show examples, and to help
>        keeping the documentation up to date. Running the doctests isn't
>        hooked up yet, but I'll work on it next.

+1... There's a chance that these tests will be rather slow to run, as 
at least for codehosting they will probably need to be written at a 
pretty high level, and so require setting up e.g. an ssh server.  But 
nothing too ridiculous, I hope.

>      * The generated HTML will be published somewhere for easy access.
>        Volunteers for this task is also appreciated.
>
>      * Documentation for Sphinx can be found at
>        http://sphinx.pocoo.org/contents.html

Cheers,
mwh