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

From: Robert Ramey (ramey_at_[hidden])
Date: 2007-11-19 12:34:12

Joel de Guzman wrote:
> Robert Ramey wrote:

> 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.

So its not the placement itself that's wrong? The error is
is only that it reviewed as part of something else rather than
independently?  So the correctness of the placement of
such a module is defined in terms of the outcome of a
formal review?  Does that seem like a practical system
to you?  Suppose static_warning.hpp were reviewed
and for some reason it was rejected and it were moved
into the serialization library.  Then we would have the
situation where two very similar libraries would be in
two entirely different places.  Would this be logical from
the standpoint of someone examining boost and trying to
understand where stuff is?  Should review results be
included as permanent part of every library?

Note
that these are rhetorical questions meant to illustrate
my view that defining the "expected placement" or
"standard whatever" which depends upon the result
of a formal review (especially when examination of
such a review) has some problems.  What is better
is a stated policy and a review acceptance process
which enforces conformance to such a policy.  Perhaps
had such a policy existed at the time and the formal
review process stated that comformance to such a policy
was one of the things to be checked, this particular
instance might be been addressed at an opportune time.

>> 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.

I previously posted the following list.  I'm not sure which
ones are convenience headers and which are not.  But
somehow I don't think they've all been independently reviewed.
given that there in the boost directory I don't know where
to look for the documentation without out doing some
sort of search.  (Hmmm - now I'm curious what something
like "none.hpp" does. ahhh - its parto of optional.hpp.)

boost/aligned_storage.hpp
boost/any.hpp
boost/array.hpp
boost/assert.hpp
boost/bind.hpp
boost/blank.hpp
boost/blank_fwd.hpp
boost/call_traits.hpp
boost/cast.hpp
boost/checked_delete.hpp
boost/concept_archetype.hpp
boost/concept_check.hpp
boost/config.hpp
boost/cstdint.hpp
boost/current_function.hpp
boost/dynamic_bitset_fwd.hpp
boost/dynamic_property_map.hpp
boost/enable_shared_from_this.hpp
boost/function.hpp
boost/function_equal.hpp
boost/functional.hpp
boost/get_pointer.hpp
boost/implicit_cast.hpp
boost/indirect_reference.hpp
boost/int_iterator.hpp
boost/integer.hpp
boost/integer_fwd.hpp
boost/integer_traits.hpp
boost/intrusive_ptr.hpp
boost/io_fwd.hpp
boost/iterator.hpp
boost/iterator_adaptors.hpp
boost/last_value.hpp
boost/lexical_cast.hpp
boost/limits.hpp
boost/math_fwd.hpp
boost/mem_fn.hpp
boost/next_prior.hpp
boost/non_type.hpp
boost/noncopyable.hpp
boost/nondet_random.hpp
boost/none.hpp
boost/operators.hpp
boost/optional.hpp
boost/pfto.hpp
boost/pointee.hpp
boost/preprocessor.hpp
boost/property_map.hpp
boost/property_map_iterator.hpp
boost/random.hpp
boost/ref.hpp
boost/regex.hpp
boost/scoped_ptr.hpp
boost/shared_array.hpp
boost/shared_ptr.hpp
boost/smart_cast.hpp
boost/smart_ptr.hpp
boost/static_assert.hpp
boost/static_warning.hpp
boost/strong_typedef.hpp
boost/throw_exception.hpp
boost/tokenizer.hpp
boost/type.hpp
boost/type_traits.hpp
boost/utility.hpp
boost/variant.hpp
boost/version.hpp
boost/visit_each.hpp
boost/weak_ptr.hpp

>> 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.

well, I'm trying to put my 2 cents in.

> 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?

I do - I was just trying to follow established patterns.  But
now you raise the real issue.  Given the size that boost
has grown to and the problems that this has engendered
I don't think that there should be anything in the boost
directory/namespace other than convenience headers.
(personally I don't even like convenience headers but
I'm think I'm in the minory on this point.)

> 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.

Hmmm - maybe

>
>>> 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.

I didn't set precedent, I followed it

> If anyone
> can do as you did, then there'll be chaos,

lots of people did and there is.

>  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.

Define a policy that is implementable.  Then you won't  have the
problem.

>> 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.

I see a big problem.  Defining the directory placement
in terms of a review means that developers can't really
make the library until after its review.  Its like sending every
court case to the legislature.  It means extra work for
developers.  It means that one doesn't really know where
to look for something.

>> 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.

Actually everything in boost should be subject to some sort
of review process.  And it is even though its sometimes
sort of informal for smaller changes and additions.

>> 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?

For a couple of reasons:

a) it's subjective and arbitrary - (one more think to be decided by 
commitee)
b) it's unnecessary - (the concept doesn't add anything)
c) it's confusiing - one looks for something in different places depending
on whether one thinks its a "core library" or not.
d) once I do #include boost/none.hpp its not obvious anymore what
other libraries my own code depends upon.
e) it's not scalable.  This is the big one.  As boost
gets bigger the number of "core libraries" (regardless of how its defined)
will have to grow.  This will make all the problems it generates
that much worse.
f) To me its inevitable that boost will have to move more toward
the spirit model of development.  That is, larger libraries, and maybe
all of them, being an asyncronous process which depends upon the latest
release of other libraries.  I know there is resistence to this, but
I think that it is inevitable regardless.  having stuff in boost/...
make this process more painful than it already its.
g) I'm already having problems with namespace clashes.
I used Multi_Index and it used aligned_storage.  Some
sort of namespace issue which seems in this case to be
precipated by a compiler bug.  So maybe its not the
best example but it took a fair amount of time to track down.
Its very confusing to have assert.hpp in boost/... as well
as in some other libraries - and can lead to hard to find bugs.

>> d) exception to a) one convenience header per library
>
> Ah, ok.

LOL - and I don't even like convenience headers myself.

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

> again, as long as those are reviewed.

well everything is reviewed.  The questions at hand would be

a) If a new library has a component which is of such a nature
that it really stands apart from the library itself, is it OK
that it be placed in a more central spot like boost/utility.

b) Is it OK for review of such a component to be
handled as part of the review for the whole library.

c) Does acceptance of a library imply acceptance
of such a component or not.

a) would be a question of policy. As these things will vary
from case to case, b) and c) things should  be added to the
review manager's checklist.

>> 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.

ReTweak: *ALL*

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

LOL - that's what I thought I was getting when I went through the TWO
orginal reviews.

Robert Ramey