Re: [sabayon] request for architecture documentation

[Daniel Veillard <veillard redhat com>]

On Thu, Mar 10, 2005 at 04:17:01PM -0500, John Dennis wrote:
> 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.)

  Completely agreed doc is good, needed, and I have a very limited view of
Sabayon internals at this point.

> 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>
> 
> _______________________________________________
> sabayon-list mailing list
> sabayon-list gnome org
> http://mail.gnome.org/mailman/listinfo/sabayon-list

-- 
Daniel Veillard      | Red Hat Desktop team http://redhat.com/
veillard redhat com  | libxml GNOME XML XSLT toolkit  http://xmlsoft.org/
http://veillard.com/ | Rpmfind RPM search engine http://rpmfind.net/