Re: Development Plan

Hi,

On Friday, October 25, 2002, at 07:26  Uhr, Brent Gulanowski wrote:
> Fellows,
>
> I will admit right up front that I am a strong believer in design when 
> it comes to any complicated system. I know that in the age of Xtreme 
> Programming I may be a minority, but I'm going to make a short pitch 
> for it (well, short-ish), and maybe some of my suggestions will stick, 
> or at least generate discussions. And those of you who do this for a 
> living, and don't need me to tell you... well, I just want this stuff 
> on record. I'm the last person to school anyone. Phil, I know you're 
> working on something design document-esque in your secret laboratory 
> -- don't read this if it will interfere!

I agree with you, we should coordinate the design and dev work, esp. 
since I will/do not have as much time as I would like to (to work on 
the 3DKit).

> If GNUstep already has rules about anything here (notably part 3), 
> let's please post a link or a FAQ or something on the website, when 
> it's possible to do so. Apologies and excuses made...
>
> Suggestions for a Development Plan for GNU 3DKit
>
> Every project can benefit from planning of some sort. I think that G3D 
> would benefit primarily from a few particular kinds of documents.
>
> 1. Produce a major feature list
> This is just an itemization of the features that G3D will offer, from 
> general interfaces and platform targets to extensibility and 
> third-party hardware/software integration and support. Features should 
> be a) ordered by priority and inter-dependency, b) given some kind of 
> rating of how much work each will require, and c) grouped in some 
> sensible way (i.e.: by component or functional relationship). If each 
> major feature (well, those slated for a milestone release, like beta1 
> or v1.0 or whatever) was broken into sub-features, that would also be 
> good. Then we can look for over-lap and/or conflicts in the 
> sub-features. Finding the right granularity for feature specification 
> can be a dynamic process.
>
> The flip-side of the feature list is the anti-feature list: what the 
> system will not do, ever. Then assumptions about what might or might 
> not happen to the code can be made explicit. It's a separate issue if 
> they turn out to be wise assumptions.

Yes, this would also help newcomers to understand what it is all about. 
I suggest we create a white paper for this purpose which eplains the 
3DKit a little.

> 2. Identify the functional sub-systems
> Software just does work that, without computers, people would do. 
> People in an organization are always broken down into departments and 
> work groups, and I think this metaphor works very well for software 
> systems. Especially when you have OOP and multi-threading, 
> multi-process, or distributed process models: these are already 
> inspired by task management and workload sharing metaphors. Metaphors 
> aren't always appropriate, but they can help visualize a system that 
> is otherwise very abstract. (I've come to see software development 
> much more like people management than like mechanical engineering, 
> except at fine granularity.)
>
> If we want to support plug-ins or other modularity (such as a 
> modularized renderer), it's helpful to identify how this division in 
> the code base will result in a division of task responsibilities. This 
> allows programmers to choose what they want to work on and concentrate 
> on it, if they desire. It helps newcomers to understand the system, 
> including newbies.

I am working on this. I also hope to make things as easy as possible by 
the layout of the PB project (see the GeometryKit as an example).

> 3. Specify the code standards
> Naming, text formatting, documentation, file layout, repository 
> directory structure, and many other things are done quite differently 
> by different developers, but the project needs to be consistent. The 
> earlier this is specified, the less re-working required.

I think we should just use the GNU standards as it is a GNU project. 
This requires reindentation of the GeometryKit as well, I assume.... 
The rules should be available on the GNU pages. We should also add the 
link to the 3DKit page.

> 4. Dependencies
> Some are obvious and some aren't. This should be quite simple. What 
> environment are we developing in, what language, what tools, what 
> dependent libraries and the like. The fact that it's a library takes 
> away some of the burden. If we extract the renderer into its own 
> module, what's left is probably not far from pure Foundation OpenStep, 
> I think, which is great. But even extracted, the renderer will deserve 
> some boundaries to be defined around it. For an OpenGL renderer, what 
> version of OpenGL? What extensions are we supporting?

Hmmm ...  this should go into the white paper mentioned above as well, 
no? But to give a final answer the design has first to be finalised.

> 5. Construction Plan
> The last main thing might be to map out the order that the first set 
> of features should be addressed -- the first batch of essential 
> features all have the same priority. I'm sure Phil has some idea of 
> what order he wants to lay things out, whether it be down-up, 
> top-down, or some other approach. I like a kind of top-down iterative 
> blend, myself -- sketch the skeleton, then add the internal organs, 
> muscles, nervous system, blood vessels, skin, sensory implant 
> junctions, bionic limb attachments, kung-fu grip -- you get the idea.
>
> I'd recommend we avoid mixing implementation discussions in the 
> development plans, if at all possible. I was just reading the OpenSG 
> "Design Document", and it (the document -- not the project, I hope) 
> must have really fallen apart while they were writing it, since it's a 
> total mishmash of fine detail speculation. It's virtually unreadable. 
> They talk about bit mask word sizes in the midst of describing the 
> thread synchronization objectives!

I try to write a first version of such a white paper covering many of 
these issues within the next few days. I will then post it via CVS and 
hope that others will jump in and provide useful 
feedback/additions/corrections.

> Finally, I don't recommend anyone sitting down and single-handedly 
> writing some monster document and then presenting it to be argued over 
> and finally ignored or made obsolete. I recommend lots of debates on 
> the discussion list, and I recommend some kind of format 
> standardization to presenting sound bites for features, systems, code 
> standards, dependencies and construction plans. I've already submitted 
> a few attempts at features/goals -- to the wrong list, I fear. But if 
> the design work is modular and collaborative, the discussion list will 
> suffice for the documentation of our intentions. I surmise this is why 
> Phil made the three distinct mailing lists in the first place.

I read your emails, it was not the wrong list..:-) It's just that I try 
to sort out my thoughts and then I will come up with a preliminary idea 
which I hope will cause some heavy discussions. From there we can plan 
the further development process.

I also understand that it is hard to jump into the project w/o having 
any real code. I really try hard to change this ASAP. I am sorry that 
it takes me so long...

> What I do hope to do, when there is enough design-oriented material on 
> the list, is to then assemble something, perhaps even a system to pull 
> information out of the list archives dynamically and assemble it into 
> a rough draft, which could be edited for clarity and cohesion. If we 
> could identify a skeleton for the development plan documentation, like 
> with section names or, even better, a numbering system, this data 
> mining process would be dramatically simplified. But it's just an > idea.

This would be really nice. Maybe you want to write a list of topics in 
a first move which can then be discussed here so that material for the 
draft can be generated for all these subjects?

-Phil
--
Philippe C.D. Robert
http://www.nice.ch/~phip