Re: [boost] [lib maintainers]Pleaseidentifyheadersinboost-root/boost

From: Joel de Guzman (joel_at_[hidden])
Date: 2007-11-19 03:05:25

Robert Ramey wrote:

> I'm not the one claiming there there exists an unambiguous
> definition of "standard practice" in this context so that's why
> I haven't claimed I followed it.  My claim is that its undefined
> and being stretched and distorted to fit with every post on
> this thread.  

The concept of "core libraries" is not new. Search the mailing
list and you'll see what I mean. I don't see it being stretched
to fit the posts. I wasn't even aware of the exchanges between
you and Dave a year ago. I noticed the misplaced header and
raised my concern.

> I don't know what it is.  I don't know where its
> defined.  That's why I had to try to extract from the example
> of the way boost was organized at the time.  Given that is the

You mention below that you based that action by following
static_assert.hpp. You see now why it is wrong? There's
a big difference -- static_assert was reviewed. Yours
is not. To be considered a boost library, it must be
reviewed independently outside of serialization.

> way I had to do it, its no wonder at least some people
> think I got it wrong.  

Who? Which libraries? If there are any, I'll raise the
same objection.

> Given the lack of definition - its inevitable
> that there is going to be disagreement on some decision which
> is supposedly based upon it.
> 
> And BTW - boost is riddled with this problem.  The same
> sorts of issues plague documentation standards, usage of
> boost/detail, release and testing procedures.

So, let's work together to fix them. Resistance to change
something that is broken does not help. You do agree that
free for all pollution of the root directory and namespace
is not good, right?

>> So, I'm curious. Is there a precedent that prompted you to
>> place static_warning in the root boost directory and in
>> namespace boost?
> 
> I just followed the example of static_assert.hpp.  I was
> new to boost so I wasn't aware of any precedent. I
> followed what seemed to me to be an inescapably
> obvious pattern.

Ok. Let's not fight on this anymore. At least we are in
agreement that something must be done to correct this.
That's good enough.

> Also the WHOLE serialization library was subject to
> review.  Everything was open to question. The first
> review produced a rejection and a very long list
> of things that were unacceptable.  The next version
> addressed all the issues raised and the library
> was accepted with very little change.  It was my
> understanding that the review was to cover all
> aspects of the library.  I could just as well argue
> that those components were reviewed.  I'm
> not going to do that however. The serialization library
> is a large library and really needed some things
> that boost didn't have like strongtypedef,
> extended_typeinfo, static_warning, and a couple
> of others I forgot.  They really arn't part of the
> library - just things boost was missing.  So I put
> them where other similar components were found
> and no one objected neither then nor for years
> afterwards.  And these things weren't hidden.  They
> were prominantly featured in the documentation
> as separate components with links to the true
> path.

Again, that's very unfortunate. We are humans and glitches
like this do happen. There's never a perfect library.
The important thing is to be able to accept mistakes like
this. It is a mistake. We can argue as much as we want,
it is still a mistake. Let's not focus on why the mistake
was committed but rather on how to correct it.

>> It's not perfect, for sure. Discussions like this, hopefully,
>> should get the issues straightened. Again, I'm curious, it
>> seems (you say) that you based your judgement from discerning
>> standard practice from existing libraries. So which is it that
>> you based placing static_warning in the root boost directory and
>> in namespace boost on? Please understand that I want to look at this
>> constructively and objectively.
> 
> I appreciate that.  See above.  Also consider the context.
> Source code, headers, test programs and documentation of
> the serialization library I believe is on the order of 30,000
> lines of text.  (we'll exclude the email discussions, reviews etc.)
> A header like static_warning is maybe 100 lines.
> I saw a very close analogy, leveraged on it, and moved on.
> Without clearer more explicity policy, one doesn't have
> much other alternative.  Actually, considering the scale
> of what was involved, the possible misplacement of a
> small number of headers (8?) is very small potatoes and
> has been blown way out of proportion.  And considering
> boost's other problems, release procedures, documentation build,
> out of date documentation standards, components used but not
> formally tested, testing on just a subset of build combinations,
> bjam, etc.  It's microscopic potatoes.

It's not microscopic for me. It sets a bad precedent. If anyone
can do as you did, then there'll be chaos, if not now, then
surely in the future. Anyway, at least you now say it's
misplaced. That's good enough. Let's work together to put them in
the proper place.

>>> So for me, its not a question so much of this or that directory
>>> structure but the whole idea that its ok to change the rules in
>>> the middle of the game.  It wastes huge amounts of time.
>> I disagree. IMO, no-one is changing the rules in the middle of the
>> game. It's just that you did something that slipped the radar
>> screen.
> 
> LOL - we could disagree on this, but as a practical matter the
> effect is the same.
> 
>> Our task now is to make sure that this does not happen.
>> And, I agree with you that we should have some kind of policy
>> written.
> 
> Halleluhuh
> 
> How about this as a policy:
> 
> a) No new headers in boost/... Boost is too big for this

Forward headers are ok. I also don't see a problem with
reviewed libraries which have a small single header to
be placed there. Ideally, the header would follow the
pattern:

     lib.hpp

where "lib" is the name of the reviewed library.

> b) small libraries can be placed in boost/utility and ancillary
> files such as tests, source code, documentation, etc be placed
> in the same spots they are as other libraries

As long as they passed the review process.

> c) No concept of "core libraries" vs "non-core" libraries

You'll have a hard time defending that. The concept of
"core library" has been with us since time immemorial.
Just search the lists. Why are you so against this?

> d) exception to a) one convenience header per library

Ah, ok.

> e) documentation in boost/libs/utility/doc/... same as other libraries

again, as long as those are reviewed.

> f) library authors encourged to move components over time
> out of boost.  This would include ALL the ones I posted
> before (except for those which are convenience headers).

Tweak: encourged to move *unreviewed* components over time
out of boost.

>>> Hmmm - well, maybe we'll just submit static_warning.hpp for a fast
>>> track review and be done with it.
> 
> I haven't done this up until now for a couple of reasons.  I thought
> it mostly redundant.  It takes a lot of time on my part.  It would
> take time from other things I thought were alot more urgent and
> important.
> 
> these would be state_saver.hpp, static_warning.hpp, strongtypedef.hpp.
> The other ones of mine are pfto.hpp, smart_cast.hpp, and I would
> be inclined to migrate them out at a convenient time in the future.  So
> you would only have about 100 others to deal with.

Why not ask for a review for all these in one shot. Dunno if that's
possible though.

Regards,
-- 
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net