Re: [boost] Breaking existing libraries

Subject: Re: [boost] Breaking existing libraries
From: Edward Diener (eldiener_at_[hidden])
Date: 2008-11-22 22:45:32

David Abrahams wrote:
> on Thu Nov 20 2008, Tomas Puverle <Tomas.Puverle-AT-morganstanley.com> wrote:
> 
>> You may or may not have noticed a thread I started on boost.users about the
>> breaking changes to Boost.Range.   Here’s a short summary:  We are currently
>> (firmwide) using boost 1.33.1.  I am in the process of trying to migrate and
>> test some of our apps with boost 1.37.  In 1.35 there was a breaking change to
>> Boost.Range with respect to how singular ranges behave.  This brings up several
>> issues:
>>
>> 1)	The breakage was silent.  The interface stayed the same but the behavior
>> changed, and drastically so.
>> 2)	No communation:  While I don’t usually post to boost.devel/boost.user, I and
>> my colleagues still read it.  Nobody recalls any mention of this on the list. 
>> Searching gmane brings up nothing, either.
>> 3)	No documentation on the boost website.  As far as I can see, this change was
>> introduced in 1.35 this March.  
>> On http://www.boost.org/users/news/version_1_35_0, there is no mention of a
>> breaking change to Boost.Range.
>> 4)	The new Boost.Range behaves differently in debug and release builds.  The
>> public function is_singular() always returns false in release builds even when
>> it would return true in debug builds.
>>
>> Apart from the fact that this change breaks a lot of our code and
>> obsoletes several useful (necessary?) idioms, the manner in which it
>> happened is far below the standards that one has come to expect from
>> boost.
>>
>> At the moment, I have to say I don’t have a good answer to how to fix
>> our code.  However, I would at least like to try to make sure this
>> kind of silent breakage doesn’t happen again.
> 
> Hi Tom,
> 
> Yes, this is an unfortunate situation.  If you indeed want to try to
> make sure this kind of silent breakage doesn’t happen again, there's
> something you can do about it: write a page of library maintenance
> guidelines on the wiki at http://svn.boost.org.  We are sorely missing a
> policy on this, and when less-experienced library authors come along,
> they often don't hew to the same standards that many of us take for
> granted.  If you don't have write permission for the wiki, please let us
> know and we'll send you an invitation.

The issue is not so much that breakage occurs but that it is sometimes
undocumented. No wiki entry is going to fix that, since there is little
in general to say about it other than the very obvious. Which is that if
any library developer, whether Boost or otherwise, makes a change from
one release to the next which changes some functionality the end-user
can use, that change needs to be documented so that end-users can easily 
see it and adjust their code which uses that library if necessary.

How Boost in particular accomplishes that is up to the Boost developers,
not the end-user community, although it is appreciated that Boost
developers may solicit input from end users about this matter as you
have done in your answer.