[sabayon] request for architecture documentation

[John Dennis <jdennis redhat com>]

I think I would be much more efficient, and I suspect other developers
who might follow would as well (Daniel, you too??), if there was high
level documentation of the sabayon software architecture. The types of
things I'm thinking of are:

* Diagram showing class relationships

* Diagram showing data structure

* Conversational description of the sequence of events illustrated with
pseudo-code

* Requirements to implement major objects (i.e. if you're writing a
delegate what methods must be implemented, how those methods will be
invoked, how the constructors have to be called, what the differences
are between implementation of a delegate vs. a source is, etc.)

I feel like I'm spending a lot of time constructing a mental model of
how all this works using grep, tags, emacs, and print statements and
this is hindering me from making implementation progress. Albeit at this
point I'm mostly over the hurdle.

As an example this morning I thought in an hour or two I was going to
add commit_change support to my delegate, but to my dismay I discovered
somehow things weren't "wired together correctly" and somehow the
FileSource was trying to call its own commit_change method thinking it
was operating on a FileChange object but was instead operating on a
MozillaChange and was throwing exceptions because the wrong objects were
being invoked. I did get it fixed, but it took about four hours
dissecting the code and building a better mental model than I had
previously. In hindsight I can see there were subtle things I missed in
the constructors (in part because defaults are provided for delegation
so you may not be aware you've missed specifying a parameter) and I
missed some subtle difference with how sources and delegates operate.

The time I've spent extracting the architecture from the code recently
would have been better spent if documentation was available. The body of
sabayon code at the moment is reasonably complex, there is a lot of
hidden stuff due to callbacks, python module magic, complex class
relationships, etc. I feel like we need to write down how this whole
thing works and the logic driving it, if not for ourselves then for
others will want to contribute to our efforts. IMHO this needs to happen
sooner rather than later.

Mark, since you've architected most of this do you think it might be a
worthwhile task to break from implementation for a moment and do some
documentation? I know the more typical sequence is build the software
first and then document it, but in this instance I think some up front
architectural documentation would be a real win and a time saver over
the course of the project. Of course I'm willing to help with some of my
new found comprehension :-)

Just my 2 cents :-) What do others think? Of course if we don't expect
to support other apps via other sabayon modules or to have other
developers involved maybe this is a moot point, but I know it would have
really helped me (especially given we're separated by multiple time
zones :-)


-- 
John Dennis <jdennis redhat com>