Re: [jamboost] Bugs/Moratorium

From: David Abrahams (david.abrahams_at_[hidden])
Date: 2002-03-24 16:13:11

----- Original Message -----
From: "Rene Rivera" <grafik666_at_[hidden]>

> Hmm, forgot about PYD targets :-( My fault. EXEs right are the only
things
> which aren't dependencies to declare-local-target.

Ah.

> >If we can all agree, I'd like to declare a moratorium on
modifications
> >to v1 other than fixes for SERIOUS bugs. There are two reasons for my
> >suggestion:
> >
> >a. in order to make progress on v2.
> >b. so that boost has a stable and working build system during v2
> >development
> ></big picture>
>
> Agreed, every time I think the feature set is done with for a while
someone
> comes up with something else, and a patch for it. One of the things
that has
> gotten us, mostly me in this case, in trouble is the lack of
documentation for
> the features that currently exist. And therefore getting broken when
new code
> comes in.

Tests are almost more important than docs. Vladimir wrote a snazzy
python testing system but I never got around to trying to use it. We'd
need a dummy toolset definition for testing purposes. All it would have
to do is echo or cat some simple data into files.

> Some of the changes I've made are my attempt at cleaning up some of
the
> convoluted code structure that has crept into V1.

Crept? Heck, it was convoluted before you ever touched it (my fault).

> Dave this is a consequence
> of the suggestions to factor out things, to clean up code.

A good idea in principle, but I think we agree...

> I think it's time to stop that. I agree it's time to stop V1
development.
> Every time I go into that code I keep wishing I was doing V2 instead
:-\

Good!

> >From V1 code point of view I'd like to see instead an effort to
document the
> current interface, what it does, or rather what it should do. We need
this so
> we can tell what's a bug or not. And we need it for V2 implementation.
This is
> the counterpart to the architecture docs of V2.

Well, I agree in principle, but in the face of realistic time
constraints I really think the emphasis should be on tests more than
docs. In any case, tests and docs support one another. It's easy to make
sure you document everything you test for, and vice-versa.

> Also any new features we think of or receive from others should,
instead of
> getting patched in, be commented on, documented and added to the V2
todo list.
> The absence of this documentation is what currently worries me about
V2 also.

Agreed. However, what worries me more is the lack of momentum. It has
been so long since we completed the architecture doc that I can't
remember what it says, and I've spent far more time with the v1 code
than with the v2 code during that time.

> We have docs on the internal implementation of V2 will be but not of
what the
> top level features it's trying to implement, other than the existing
V1 code.

Partly that's because we really have a code /framework/, with both
programmer-level and user-level functionality, and there's a continuum
between users and programmers of this system. That can make it difficult
to decide which elements to expose in the top-level docs.

What do you think needs to be covered in the top-level docs which
currently isn't?

> And as we all know code is the worst documentation ;-|

Yep.

> >**No, it's not just Rene. I did the PYD and vc6/vc7 stuff, which I
> >needed for my own work.
>
> Yep, we all do it because of our work. I was eager to put in the
template rule
> because it will immediately help in cleaning up my ever growing number
of
> Jamfiles in my project.

I should really apply it to Python, now that we have it. Strangely,
there's no really good place for it at the moment, because the
python.jam module doesn't have an identity in the (sub)project
hierarchy...

-Dave