launchpad-dev team mailing list archive

[Bjorn Tillenius <bjorn@xxxxxxxxxxxxx>]

Hi guys,

so, it's time for the Technical Architect team to tackle its first task.
Create the Launchpad Architectural Vision.

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

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

Anything missing?

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.

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.

    * 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


-- 
Björn Tillenius | https://launchpad.net/~bjornt