Richard writes:

[Please do not mail me a copy of your followup]

I can take over the library.

Thank you for this concise but generous offer, but I personally am not yet convinced this is the best for library future (aside from the fact that I am still interested in maintaining it as well ;) ) Regards, Gennadiy

Richard writes:

Hi Richard, I am not sure why do I need to keep justifying myself for you.

There is a doc bug revolving around a single character edit that is 5 years old and remains unfixed. https://svn.boost.org/trac/boost/ticket/2717

This one is fixed in trunk long time ago.

There are quite a number of open issues and many of them are quite old: <https://svn.boost.org/trac/boost/query? status=assigned&status=new&status=reopened&component=test&col=id&col=summary &col=status&col=owner&col=type&col=time&col=cc&order=priority>

This is just show again that many (if not most) of your claims are baseless or based on some misconceptions. Not everything that is in trac is an issue. There are indeed some long standing feature requests (like support for multithreading or performance testing). Some repetition. Many opened/reopened tickets for docs fixes, which already addressed in trunk, but I did not close them until docs are released (it is convinient for me to keep them open as a reminders). There are indeed few issues open last half a year, which might need an attention, but they are mostly with trunk changes, which you do not care about anyway.

You have admitted that you don't have sufficient time to properly maintain the library.

I never said that. I may not have enough resources to push new release out and develop new features, but I am going to find a way around this, even though you are not interested to help. I think from now on I'll liberate myself from replying to your posts, which are not helpful and only waste my time. Gennadiy

Andrey Semashev writes:

I'd like to point out that if a bug has been fixed in trunk/develop but the fix has not been merged to release/master, the bugfix is not delivered to users and is as good as not fixed.

That's why ticket is not closed.

If you fixed a bug in trunk but didn't find a chance to merge the fix to release for years then you clearly don't have the resources to properly maintain the library. "It's been fixed in trunk" is not an excuse.

I think you not exactly appreciate amount of time/effort it require to push the change in core library to release branch. Regardless of number of maintainers, this is still has a significant probability of being disruptive and I decided not pursue it unlesss I have a lot of time time to address the issues and really good reason to back up the change. The best policy is to push changes in batches, but now Iam stuck, since I can't push latest changes till I document them. Gennadiy

[Please do not mail me a copy of your followup] boost@lists.boost.org spake the secret code <5870254.kYyq64tnod@lastique-pc> thusly:

I think it is best to push changes in small chunks (maybe, each feature separately) but often.

Yep. Small incremental changes are always better than a giant set of changes. With the giant set, when something breaks, you don't have any good idea what caused the failure. This is pretty basic agile development/large-scale development advice. -- "The Direct3D Graphics Pipeline" free book http://tinyurl.com/d3d-pipeline The Computer Graphics Museum http://computergraphicsmuseum.org The Terminals Wiki http://terminals.classiccmp.org Legalize Adulthood! (my blog) http://legalizeadulthood.wordpress.com

Vicente J. Botet Escriba writes:

What about forking the Boost.Test library into a new Boost.XTest with the contents of the Boost.Test release and your documentation and taking care of the issues associated to the release branch?

I do not believe this is a good solution. The intersection (name collision) between two libraries is going to be way too big and we'll never know which one code refers to (user complains about). This will lead to no end of confusion. Richard is free to develop a new library from scratch and eliminate all the things he believes are not important (and for that matter add anything he believe is lacking), pass it through the review and maintain it.

What the Boost community thinks about this proposition? Will competition between two libraries be a good thing for Boost?

We had few examples like this, but I do not think this is ideal. At least libraries should present different tradeoffs for users: one big but complete, another one is small, but not as extendible (or something along these lines) Gennadiy

On 22.01.2014 13:07, Tim Blechmann wrote:

besides: competition often leads to better products, imo clang is the best thing that happened to gcc ... i had my troubles with boost.test myself, so also from the perspective of the user it would be very helpful to have two libraries with a similar interface, which could be exchanged by using a different namespace or macro prefix.

that said, i have no idea, why you strongly dislike richard's offer

Presumable it is because Richard's offer -- which I trust was genuine offer of engineering help -- actually sounded like an offer to take over something that Gennadiy has spent years creating, over close to 900 commits. The resulting response was rather on the polite side, even. I don't know whether damage done in this thread, and in other exchanges about boost.test, can be undone :-( - Volodya

On 01/22/2014 12:13 PM, Tim Blechmann wrote:

Vladimir wrote:

...

I don't know whether damage done in this thread, and in other exchanges about boost.test, can be undone :-(

sad, but true. though having more than one maintainer for a library would be the best approach for a stable codebase ...

As far as what I understand, that is what Gennadiy offers. Richard's offer was more along the line, "I will take over if you get out of my way". At least that is what I interpreted. I would not be so eager for a fork, unless there is no other way. It may be Gennadiy need help, and he ask for help. Richard did not offer any help in this exchange at least. As far as the documentation, I find it hard to understand why the various views on the Library that Richards documentation and the original documentation represent could not be integrated somehow to a better total. However if the attitude is that we have new docs, get rid of the old. Anybody see a pattern here? I have very little understanding of how that should work to the better of Boost. -- Bjørn

On 01/22/2014 10:30 PM, Alexander Lamaison wrote:

Bjørn Roald writes:

...

As far as the documentation, I find it hard to understand why the various views on the Library that Richards documentation and the original documentation represent could not be integrated somehow to a better total. However if the attitude is that we have new docs, get rid of the old. Anybody see a pattern here? I have very little understanding of how that should work to the better of Boost.

A lot of the old documentation is not useful for Boost.Test users, and it swaps the bits that are useful. For example, the first two chapters are about the execution monitor and the program execution monitor, two details that the Boost.Test users never need to know about. Users have to read to Part IV before they find out how to use the library in the recommended manner.

Sure, I do agree with you that these are problems with the current documentation from the view-point of a typical library user. I have been struggling with this myself almost every time I have refereed to the docs for simple advise of setting up some ad-hock tests for a project. That does not mean that there are not other view-points or aspects of Boost.Test that deserve documentation. The key issue for improvement is that the resulting documentation need to be clear about which sections are the more useful to "just" get started using Boost.Test, so the average developer that are just trying use Boost.Test will simply skip less interesting parts, or simply not get there as it is deep in some reference section, or documentation for maintenance and design of the library itself. Some structural change is needed to make these sort of aspects very explicit and clear if any sort of combination of the docs are to be useful.

Once you cut it down to size, you would result in what Richard has written, albeit, less clearly worded.

Well, I think this statement is very heavy biased on the view that no other aspect of Boost.Test than those that has concerned Richard are the worth documenting. If that where a global and final truth, then it would be a valid assertion, but it is not.

That's why combining the two would not be better: a major benefit of Richard's is the _absence_ of documentation.

Yes shorter is in general better, no doubt. But, to be true, that assumes the shorter version provide the same or at least a sound level of information completeness. Removing potentially useful information in the name of brevity may be a very bad idea. By the way, I am not simply suggesting that to combine the available docs would improve anything. I was suggesting the various views could be integrated somehow. What I had in mind is far from simply adding a new section for Richards stuff. As it stands, without some adjustments in the attitudes of the major stakeholders here with regards to each other's work, I see little hope of this happening. That is a sad thing as I think their combined effort and respect could have led to much more than two competing efforts is likely to ever do. -- Bjørn

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Alexander Lamaison Sent: Friday, January 24, 2014 10:39 AM To: boost@lists.boost.org Subject: Re: [boost] [test] Looking for co-developer/maintainer

...

As it stands, without some adjustments in the attitudes of the major stakeholders here with regards to each other's work, I see little hope of this happening. That is a sad thing as I think their combined effort and respect could have led to much more than two competing efforts is likely to ever do.

Maybe so. But anger is keeping the two groups apart.

One camp is angry that they tried to involve the maintainer, got no response, worked hard to solve it themselves, then the maintainer reestablishes contact just to object once the work is done. The maintainer's camp is angry that the others have gone away and decided his documentation, which took years to write, is bad and needs replacing without his consent.

It's hard to see how to resolve that in a way that satisfies both sides.

This isn't just a two-sides issue. There are also a lot of Boost users and developers who have been unhappy with Boost.Test documentation, evolution, and maintenance for over about a decade. It is clear to me that Gennadiy is not willing to cooperate with anyone. I'd have sympathy with a 'too many cooks spoil the broth' view if he was maintaining the library well, but ... This is why I think that a fork *is* now a good idea at this time for two reasons: 1 It will minimize the disruption to testing that any changes to Boost.Test inevitably risks. 2 I'd like to see a much simpler faster lighter-weight header-only version of Boost.Test with a different name and a different maintenance *team*. Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com

[Please do not mail me a copy of your followup] boost@lists.boost.org spake the secret code thusly:

* I did not see yet a single library which is simpler

There are many that are simpler. One is even inside boost itself: is one that several library owners have told me that they use instead of Boost.Test because B.T. kept breaking their builds and the documentation was not usable.

* No one ever expressed a problem with Boost.Test being slow

Quite a bunch of people expressed frustration with the compile time at the C++ Now! 2014 workshop.

* Boost.Test is header only (has an ability)

This one is particularly hard on the compile times. -- "The Direct3D Graphics Pipeline" free book http://tinyurl.com/d3d-pipeline The Computer Graphics Museum http://computergraphicsmuseum.org The Terminals Wiki http://terminals.classiccmp.org Legalize Adulthood! (my blog) http://legalizeadulthood.wordpress.com

On 29 May 2014 at 8:29, Gennadiy Rozental wrote:

...

is one that several library owners have told me that they use instead of Boost.Test because B.T. kept breaking their builds and the documentation was not usable.

Boost.Test does not change for many many years now

This is untrue. Here is an example of a recent Boost.Test change induced break: Note the #ifdef testing Boost.Test version: https://github.com/BoostGSoC13/boost.afio/blob/master/libs/afio/test/t est_functions.hpp#L160 Note the fact we need this at all is because Boost.Test won't timeout tests in a sane way (or at all on Windows), so we reimplement the functionality such that it actually works. I never got round to reporting this on the bug tracker, apologies.

...

...

* No one ever expressed a problem with Boost.Test being slow

Quite a bunch of people expressed frustration with the compile time at the C++ Now! 2014 workshop.

Do you have any numbers? How many seconds does it take to build Boost.Test shared library based test module vs. one built using other alternatives?

Boost.Test should default to not being header only. It's the only library in Boost I feel that way about. There is no good reason for a full fat unit test library to be header only. AFIO forces library only Boost.Test, and we saw a very dramatic improvement in CI turnaround times. A huge win. Niall -- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/

On Jan 24, 2014, at 11:16 AM, Gennadiy Rozental wrote:

Alexander Lamaison writes:

...

I'm genuinely curious what aspects of Boost.Test, that Richard ommitted to document, you use. Maybe I'm far off the mark, but I doubt many people use the extra stuff that is basically an implementation detail.

These are not implementation details at all. The fact that you are not using them does not make them useless. There are some people (admetedly less then those who are suing UTF) who need these to be documented.

I'm a long-time user of Boost.Test (> 8 years). I personally have found the level of detail in its documentation very useful over those years. Sometimes one makes a usage mistake, especially when trying to do something complicated that is beyond what is described in the tutorial examples, and sometimes the errors one gets (either from the compiler or at runtime) are less than helpful. Despite that, I've never had to resort to looking at the Boost.Test source code to resolve such issues. That's not something I can say for a lot of the code I work with, including some other Boost libraries. So when I hear someone suggesting that there is too much detail in the Boost.Test documentation, and that some of it should be thrown away, I get very nervous. While I will certainly agree that the existing release documentation has some structural / organizational problems, that's an entirely different problem. [And one which no longer has much effect on me personally, since I've invested the time needed to know my way around in the current documentation.]

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Darryl Green Sent: Monday, January 27, 2014 11:41 AM To: boost@lists.boost.org Subject: Re: [boost] [test] Looking for co-developer/maintainer

On 25 January 2014 08:52, Kim Barrett wrote:

...

On Jan 24, 2014, at 11:16 AM, Gennadiy Rozental wrote:

...

Alexander Lamaison writes:

...

I'm genuinely curious what aspects of Boost.Test, that Richard ommitted to document, you use. Maybe I'm far off the mark, but I doubt many people use the extra stuff that is basically an implementation detail.

These are not implementation details at all. The fact that you are not

...

them does not make them useless. There are some people (admetedly less

using then

...

those who are suing UTF) who need these to be documented.

I'm a long-time user of Boost.Test (> 8 years).

While I will certainly agree that the existing release documentation has some structural / organizational problems, that's an entirely different problem. [And one which no longer has much effect on me personally, since I've invested the time needed to know my way around in the current documentation.]

+1 to all that. Richards documentation efforts so far, are definitely a step in the right direction - a clearer and well structured lead in to using the library with the features explained as they are needed is what the

needed.

However docs on extending and using the lib beyond basic use cases (eg traversing the tests for producing custom result formats) are much needed. The docs on how the library works "internally" are needed to be able to use those extension points effectively.

FWIW, I suspect there is a large and silent (especially in this forum) user base of boost test

library that are for

the most part quite happy with the (if this thread is to believed) terribly unmaintained and broken boost.test in release. Hopefully a new and improved version can be released without breaking things - from where I sit its the rest of boost that changes wildly (a great thing - keep pushing that envelope) that is the challenge, not the stability of boost.test. My personal experience is limited to Windows x86, Windows CE ARM, Linux x86 and Linux ARM across a range of "vintage" and not so vintage compilers, but it "works for me".

Which is precisely why I believe we should not mess with the current release. It's the devil we know. Boost.Test has suffered mission creep. I believe that most would be well served by a simpler faster version. It could use the same MACRO names and would probably just drop in for many uses. It must have good documentation in a community maintainable form. The best way to avoid any disruption is to invite proposals for Boost.SimplerTest and let developers decide if and when to change. The two (or more) libraries can coexist happily for ever if necessary. Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com

[Please do not mail me a copy of your followup] boost@lists.boost.org spake the secret code thusly:

However docs on extending and using the lib beyond basic use cases (eg traversing the tests for producing custom result formats) are much needed.

That's a reasonable request. However, this information is missing from the current documentation, so my version doesn't make things any worse. I am curious how many people need this advanced functionality. If one person needs it, then it's lower priority than if a bunch of people need it.

The docs on how the library works "internally" are needed to be able to use those extension points effectively.

None of this is documented currently.

FWIW, I suspect there is a large and silent (especially in this forum) user base of boost test [...]

From my discussions with people outside this mailing list (in person, user groups, code camps, other newsgroups, etc.), most people are not happy with Boost.Test's documentation. Wait, let me rephrase that. I don't think I've met or conversed with a single person who was happy with the existing documentation, not even it's author.

The poor state of the documentation is 's why I wrote tutorials on how to do TDD with Boost.Test in 2009. That's almost FIVE years ago at this point. Those tutorials are the most heavily accessed postings on my blog, by an order of magnitude. That was what told me that the documentation needed to be overhauled. If the documentation was doing it's job, then my blog tutorial posts would just be getting the same amount of hits as other posts on my blog. I waited patiently for the documentation to get better. I don't think it has hardly changed at all in that time. Let's be completely honest here. There are many C++ unit testing frameworks out there. The main competitor for Boost.Test is gtest/gmock. Most people, when faced with the poor documentation and poor response to questions of Boost.Test, simply stop trying to use it and switch to gtest/gmock. Or the documentation alone is enough to turn them away towards gtest. This is making gtest/gmock the pre-eminent unit testing tool for C++ code out there in the wild. Boost has been losing mindshare and leadership here for a long, long time -- at least 5 years and probably more. This is why "Modern C++ Programming with Test-Driven Development" by Jeff Langr, which came out in Oct. 2013, uses gtest primarily in it's discussion and examples. Boost.Test barely gets a mention in the appendix of the book and I know why -- it's difficult to understand and the community also struggles with understanding and using it effectively, so it's hard to get good answers from the community. Even within the boost community several people have come out and explicitly stated their distaste for Boost.Test, it's documentation and the way it has been maintained. At least two library authors have corresponded with me in private stating that Boost.Test too often breaks their code and the only solution they see to that problem is a *different* maintainer. Looking forward, I don't see the current path as changing the ultimate outcome: Boost.Test will continue to be used less and less, only people with an existing investment in using it will continue to use it. gtest/gmock will continue to be used more and more and will become the defacto standard for new development. -- "The Direct3D Graphics Pipeline" free book http://tinyurl.com/d3d-pipeline The Computer Graphics Museum http://computergraphicsmuseum.org The Terminals Wiki http://terminals.classiccmp.org Legalize Adulthood! (my blog) http://legalizeadulthood.wordpress.com

[Please do not mail me a copy of your followup] boost@lists.boost.org spake the secret code thusly:

On 20 February 2014 05:54, Richard wrote:

...

[Please do not mail me a copy of your followup]

boost@lists.boost.org spake the secret code thusly:

...

However docs on extending and using the lib beyond basic use cases (eg traversing the tests for producing custom result formats) are much needed.

That's a reasonable request. However, this information is missing from the current documentation, so my version doesn't make things any worse.

Yes it does. It doesn't even mention or imply that it is possible. There are hints that you can extend (yes, the docs are not good - but that is different from missing) for example:

http://www.boost.org/doc/libs/1_55_0/libs/test/doc/html/utf/user-guide/test-...

When I browse that URL I just get a list of section headings. In what way does this document extensibility? As you say, the docs contain hints, but no explanation of how to do it. I've read through them.

...

I am curious how many people need this advanced functionality. If one person needs it, then it's lower priority than if a bunch of people need it.

Well, as you apparently talk to lots of boost test users - ask them.

I have. Except for this specific thread, noone has stated that they need this.

All I know is that I needed it and others clearly have otherwise I wouldn't have found questions and answers including code examples on the web. It would be nice to have it in the docs.

Can we get back to specifics? What "it" do you want in the docs?

traversing the test tree: http://stackoverflow.com/questions/8550704/boost-unit-test-list-available-te...

This is actually not a question about traversing the test tree so much as it is a question about how to list the available tests. As the maintainer pointed out, there is a new command-line argument that provides this functionality. (I actually had documented it in an earlier snapshot, but took it out when I realized that this command-line argument appears in no shipping version of the library.)

custom log formats: http://www.eld.leidenuniv.nl/~moene/Home/projects/testdox/boosttest/

This page is actually dead now. I had to get it from Google's cache from May 1, 2014. This is also not about a custom log format, but is about getting the test names from the library so that documentation can be created from those test names. This is also serviced by the --list-content argument.

But regardless - Are we going to start voting for which public interfaces of boost libraries should be documented or can we take it as a given they all should be?

Because so much of the content of Boost.Test header files has remained undocumented for so long, it is unclear what is an implementation detail and what is an interface without documentation.

You have argued quite strongly *against* documenting these features in this thread.

Meh. I am not the author of the library, so I can only comment as a user of the library since ~2005 what I perceive to be implementation detail compared to useful API surface. I added things that weren't documented that I thought were important to know, like how to write a custom predicate, among other things. Off the top of my head, the main thing I left out were details about the program execution monitor. This is a mechanism implemented in Boost.Test to ensure that the library can report errors as much as possible. I don't know anyone who uses this component by itself, but it was documented before and I didn't spend any time documenting it in the rewrite. Am I saying I *won't* document it? No, I'm saying that in almost a decade of using this library and in consulting with other programmers who use this library in meatspace as well as mailing list space, I have never talked to a single person who used it outside the library itself. -- "The Direct3D Graphics Pipeline" free book http://tinyurl.com/d3d-pipeline The Computer Graphics Museum http://computergraphicsmuseum.org The Terminals Wiki http://terminals.classiccmp.org Legalize Adulthood! (my blog) http://legalizeadulthood.wordpress.com

[Please do not mail me a copy of your followup] boost@lists.boost.org spake the secret code thusly:

...

When I browse that URL I just get a list of section headings.

In what way does this document extensibility?

As you say, the docs contain hints, but no explanation of how to do it. I've read through them.

Agreed there is no explanation. But clearly the list of section headings includes the heading *Custom report format support* as well headings for several other ways of controlling report output. To that extent it documents that extensibility exists. This is better than not mentioning the capability at all.

I think reasonable people can disagree on whether this is better or not :-).

Your doc would be no worse then the original if it simply stated that these features existed. Anything else is an enhancement request...

I agree with this. If I were going to need custom reports, I'd take the XML report output and run it through a XSLT file before I spent time writing code, but maybe writing C++ is easier for people than XSLT.

...

Can we get back to specifics? What "it" do you want in the docs?

The *it* is to use your words *this advanced functionality* or to use the words missing from your docs *custom report format support*.

In other words, except for the missing hint, these aren't deficiencies of my docs compared to the existing docs.

Regardless of the question, the answer to the question requires use of the API (or a commandline option that doesn't exist). The documentation should provide answers, not questions.

AFAIK, the existing documentation does not explain how to use the implementation classes to traverse the test tree. So this is an enhancement.

...

...

custom log formats: http://www.eld.leidenuniv.nl/~moene/Home/projects/testdox/boosttest/

This page is actually dead now. I had to get it from Google's cache from May 1, 2014. This is also not about a custom log format, but is about getting the test names from the library so that documentation can be created from those test names. This is also serviced by the --list-content argument.

I don't know what page you got from a cache but the page I (re)got just now (absolutely not from a cache - via https to be extra sure) is exactly about a custom output format. Maybe a DNS issue or maybe a temporary outage?

Yes, appears to be a temporary outage. Again, this is something that the existing documentation does not explain at all, other than perhaps hinting that you can have a custom report. ok, so you want: 1) custom report format support 2) (and I assume, it's cousin) custom log format support 3) traversing the test tree AFAIK, other than hints, these are all additions to the existing documentation. (In fact what I wrote about the report format is already an addition to the existing docs.) So achieving better than parity with existing docs would be to simply say "You can customize the report output; see <this example>" and link to that url.

You have twice asserted that uses of the API can be replaced by use of a commandline argument. This is not really true (it doesn't solve my use case)

Not sure what your use case is, but definitely listing out the tests in your project and getting custom report or log output can be handled without writing C++ code, albeit you might need to write some XSLT code.

I agree it is unclear. I'm only trying to provide some clarity (with sources) as to what is demonstrably already intended to be and in use as part of the interface, so that the docs can make that clear.

I think you raise some reasonable immediate points that can be addressed by adding a few sentences. Longer-term you're asking for new documentation on classes in the library. I think that is also a reasonable request, but it's beyond the scope of what I'm trying to obtain with this change.

...

[I left out stuff about the Program Exeuction Monitor (PEM)]

I agree it isn't used by itself. However knowing what it does (and some level of how at the level of identifying what platform specific features it uses) is useful.

Is it really? To me, it's an implementation detail. The main thing you need to know about the PEM is that it attempts to intercept all badness and capture that as a test failure: unix signal(2), Windows SEH style exception, and C++ uncaught exception.

...

Am I saying I *won't* document it? No, I'm saying that in almost a decade of using this library and in consulting with other programmers who use this library in meatspace as well as mailing list space, I have never talked to a single person who used it outside the library itself.

Assuming this "it" use the program execution monitor, that is consistent with my own experience, fwiw.

Yes, by "it" I'm referring to the PEM. -- "The Direct3D Graphics Pipeline" free book http://tinyurl.com/d3d-pipeline The Computer Graphics Museum http://computergraphicsmuseum.org The Terminals Wiki http://terminals.classiccmp.org Legalize Adulthood! (my blog) http://legalizeadulthood.wordpress.com

[Please do not mail me a copy of your followup] boost@lists.boost.org spake the secret code <6F8C95D8-715C-4900-96A1-4EAF1B4B8EC8@verizon.net> thusly:

[...] So when I hear someone suggesting that there is too much detail in the Boost.Test documentation, and that some of it should be thrown away, I get very nervous.

Have you looked at my version of the documentation? http://user.xmission.com/~legalize/tmp/boost.test/libs/test/doc/html/index.h... What is missing from there that you feel needs to be documented? -- "The Direct3D Graphics Pipeline" free book http://tinyurl.com/d3d-pipeline The Computer Graphics Museum http://computergraphicsmuseum.org The Terminals Wiki http://terminals.classiccmp.org Legalize Adulthood! (my blog) http://legalizeadulthood.wordpress.com

[Please do not mail me a copy of your followup] boost@lists.boost.org spake the secret code thusly:

These are not implementation details at all. The fact that you are not using them does not make them useless. There are some people (admetedly less then those who are suing UTF) who need these to be documented.

Specifics, please. Again the general statement is made without specifics.

For example? Which undocumented macros?

It's difficult to list them one by one because the existing documentation has no suitable index that clearly lists all the symbols that it explains.

Richards, version has some number of pages with Richards view on how one should be testing things, but these are just views for the most part. We might want to keep something like this in "suggestions" sections.

It's in the user guide. You make this statement as if what I wrote was somehow "just my opinion", when in fact it is the common practice in unit testing. Nothing I wrote is inconsistent or contrary to the advice in Kent Beck's "Test-Driven Development", Jeff Langr's "Modern C++ Programming with Test-Driven Development", Freeman & Pryce's "Growing Object-Oriented Software, Guided by Tests", Gerard Meszaros's "xUnit Test Patterns: Refactoring Test Code", and so-on. In other words, I documented the typical industry practice. I think this is important for people who are new to unit testing. They should work *with* the accepted norms before they develop enough skill and expertise to know *when* and *how* they should deviate from them.

In my opinion I have expressed desire to work with anyone on new documentation, who is willing and interested. This offer still stands.

Then you'll obviously be taking my pull request when I issue it soon. -- "The Direct3D Graphics Pipeline" free book http://tinyurl.com/d3d-pipeline The Computer Graphics Museum http://computergraphicsmuseum.org The Terminals Wiki http://terminals.classiccmp.org Legalize Adulthood! (my blog) http://legalizeadulthood.wordpress.com

On Mon, 19 May 2014 15:37:33 -0700, Richard wrote:

[Please do not mail me a copy of your followup]

Bjørn Roald spake the secret code <52E051FA.8030202@4roald.org> thusly: [snip]

...

As it stands, without some adjustments in the attitudes of the major stakeholders here with regards to each other's work, I see little hope of this happening. That is a sad thing as I think their combined effort and respect could have led to much more than two competing efforts is likely to ever do.

Sorry, I have to laugh at some of the mind-reading that goes on in these threads. How does anyone besides the parties involve have any idea how much "respect" is contained in their minds? To my knowledge, noone involved has made any explicit statements.

I see a problem and I do a crapton of work to fix it, but somehow I get labelled, either implicitly or explicitly, in these threads as a bad actor that has "no respect" for others or that I'm needing an "attitude adjustment".

If all of you had joined in my call for reviewers many, many months ago, you could have expressed whatever concerns you had then and made sure that work proceeded as you thought it should. But no, you did nothing. You did not participate. You come in at the last minute and basically insult my character. What the hell does that say about this community?

Ouch, that's a little harsh. Unfortunately these kind of statements take away from the merits of your argument. You don't want the last impression left on people's mind to be that Richard's a crank and therefore let's ignore him, even though your work maybe quite solid. You've noted that you're not interested in forking the library. Why not just "fork" the documentation. That is permanently host your alternative documentation somewhere else, and every time you post to a ML include a link to it. That, and if your documentation proves popular enough it will show up in the top one or two spots on Google and it will then become the "defacto" documentation.

On 05/20/2014 12:37 AM, Richard wrote:

[Please do not mail me a copy of your followup]

Bjørn Roald spake the secret code <52E051FA.8030202@4roald.org> thusly:

...

On 01/22/2014 10:30 PM, Alexander Lamaison wrote:

...

Bjørn Roald writes:

...

As far as the documentation, I find it hard to understand why the various views on the Library that Richards documentation and the original documentation represent could not be integrated somehow to a better total. However if the attitude is that we have new docs, get rid of the old. Anybody see a pattern here? I have very little understanding of how that should work to the better of Boost.

A lot of the old documentation is not useful for Boost.Test users, and it swaps the bits that are useful. For example, the first two chapters are about the execution monitor and the program execution monitor, two details that the Boost.Test users never need to know about. Users have to read to Part IV before they find out how to use the library in the recommended manner.

Sure, I do agree with you that these are problems with the current documentation from the view-point of a typical library user. I have been struggling with this myself almost every time I have refereed to the docs for simple advise of setting up some ad-hock tests for a project. That does not mean that there are not other view-points or aspects of Boost.Test that deserve documentation.

If someone gives me SPECIFIC feedback on where my documentation needs to be improved before it should be accepted as *the* documentation, I'm happy to address that.

So far I haven't gotten any SPECIFIC suggestions, just vague hand-waving that somehow these new docs aren't good enough.

I don't know if anybody said they where not good enough. For sure I have not. I have just tried to express concerns about the round-about approach of replacing everything given that the maintainer is concerned that the new documentation does not cover some of the detailed documentation for customizing and maintaining the the library.

Is something missing? Name it.

Is some description confusing? Point me to it.

Is some description incorrect? Point me to it.

I have not expressed any critique of the new docs as documentation for the user of Boost.Test. I see the new docs as a clear improvement and I hope it will be included. Or better, replace the relevant parts or all of the of the existing docs, whatever the maintainer find best. I think your Pull Request was a good move. It is now up to the maintainer to handled as it should. If it is integrated, I hope you will continue your contributions.

Let's not get so hung up on generalities that we hold something back for some unspecified deficiencies, because unless we can name the specific deficiencies, it is a pointless objection.

Agree.

...

[...] Some structural change is needed to make these sort of aspects very explicit and clear if any sort of combination of the docs are to be useful.

Exactly why I did a rewrite. The structure and organization was not useful for people who wanted to just get on with using this library.

Agree.

...

Well, I think this statement

[[Please don't remove too much context. It is hard to follow the arguments.]]

...

is very heavy biased on the view that no other aspect of Boost.Test than those that has concerned Richard are the worth documenting. If that where a global and final truth, then it would be a valid assertion, but it is not.

Again: please point out something specific that needs documenting that I left out. Unless you have read both sets of docs end-to-end, you may be assuming that something is missing when in fact it is present and simply discussed in a different section or what have you. I know for a fact that there are things in my docs that have been present in the library all along and were useful to all users but that were NOT documented at all.

My reply to this would just be repeating what I have written above.

...

...

That's why combining the two would not be better: a major benefit of Richard's is the _absence_ of documentation.

Again, please be specific. This statement has been made several times on these threads without getting to specifics.

The quote you respond to here is not mine, nor is it critique of your docs.

...

[...] What I had in mind is far from simply adding a new section for Richards stuff.

I think if you do that, it will frankly be the only section that anyone looks at.

[[The way you quote, and leave out relevant context, this discussion is hard to follow.]] I take it that you are saying noting in the existing docs is worth keeping because nobody will ever read it. I will certainly not stand behind that statement. I would leave that up to the maintainer to decide.

...

As it stands, without some adjustments in the attitudes of the major stakeholders here with regards to each other's work, I see little hope of this happening. That is a sad thing as I think their combined effort and respect could have led to much more than two competing efforts is likely to ever do.

Sorry, I have to laugh at some of the mind-reading that goes on in these threads. How does anyone besides the parties involve have any idea how much "respect" is contained in their minds? To my knowledge, noone involved has made any explicit statements.

Well, did you not just state that nobody will ever read any of the existing docs that the maintainer would like to keep?

I see a problem and I do a crapton of work to fix it,

And your efforts are very appreciated

but somehow I get labelled, either implicitly or explicitly, in these threads as a bad actor that has "no respect" for others or that I'm needing an "attitude adjustment".

I take it that there is some expression of frustration in past posts, I think that is understandable. It just does not seem to be bringing anybody together to a joint effort. So if that is desired, more care with what is written on the list may be a good thing.

If all of you had joined in my call for reviewers many, many months ago, you could have expressed whatever concerns you had then and made sure that work proceeded as you thought it should. But no, you did nothing. You did not participate.

Right, and I have never argued that there is anything wrong with your work. The arguments have been about how to get your work properly into Boost.Test. So I don't think it is relevant to what degree I have participated in reviews.

You come in at the last minute and basically insult my character.

I hope I have not done that. It has not been intended and if I did I sincerely apologize.

What the hell does that say about this community?

I really do not know how to respond to that. I think people here try to do their very best to help each other. If you interpret my words trying to describe what I observe as any thing else, then I am sorry for that. I think you have done a very good thing working on these docs and offer them for integration into Boost.Test. If your documentation for some reason does not make in into or replace the official Boost.Test docs, then I am sure there are other excellent places for it, such as in the tools section on the Boost web pages. If that is not satisfying, the alternative is a full fork which I hope it will not get to.

This work was not done in secret, nor in isolation. It was explicitly labelled as a rewrite and not an edit or evolution from the very beginning.

Unless I have seriously misunderstood something fundamental here, that does not by itself earn your documentation the right to replace everything in the old docs in the end. Your assertion that that is the case has been the core of my concern. I know your point of view have a lot of support, and I am not saying that point of view is wrong. I just had the feeling there where some viable arguments made by Gennadiy and it is a bit beyond me why that could not be listened to, accepted and somehow resolved.

The participation was open at every step of the way. To show up at the end and complain about how things were done doesn't earn much respect in my eyes.

Again, I never complained about the documentation, or how it was created. It is an improvement in my mind, and I have never said anything else. So I do not follow your point here. Exactly what do you refer to when you say I "complain about how things were done"? Thanks, -- Bjørn

[Please do not mail me a copy of your followup] boost@lists.boost.org spake the secret code <52DFF857.80500@4roald.org> thusly:

On 01/22/2014 12:13 PM, Tim Blechmann wrote:

...

sad, but true. though having more than one maintainer for a library would be the best approach for a stable codebase ...

...assuming that the two maintainers share the same vision for the library.

As far as what I understand, that is what Gennadiy offers. Richard's offer was more along the line, "I will take over if you get out of my way". At least that is what I interpreted.

Yes, that is what you interpreted, but you are reading more sinister things into it than I said -- the "if you get out of my way" part. I simply offered to take over as maintainer. As I said in another reply on this thread, he can refuse the offer and it makes no difference to me.

I would not be so eager for a fork, unless there is no other way.

For the record, I am not interested in a fork. People keep suggesting this generally or to me specifically and I am not interested in forking. It doesn't really fix anything in this situation.

It may be Gennadiy need help, and he ask for help. Richard did not offer any help in this exchange at least.

Nonsense. The biggest weakness of Boost.Test has been the documentation and I basically fixed that. If you don't consider this to be help, then hell if I know what it is to be helping.

As far as the documentation, I find it hard to understand why the various views on the Library that Richards documentation and the original documentation represent could not be integrated somehow to a better total.

If I thought that the problems with the existing documentation could be substantially corrected by minor changes, then I would have done that. I struggled with this for many months to try and figure out a way to submit bug reports that would evolve the existing docs into something useful. However, I couldn't find a way to do that without basically rewriting the whole thing one bug report at a time. That seemed like a pointless churn through the trac system, so I simply set about rewriting them, with a call for reviewers here. For whatever reason, I never got any email from the maintainer saying he wanted to be involved in that process and I never saw any posts in the gmane newsgroups to that effect either, so this rewrite went on for months with several snapshots and feedback from reviewers before I posted here for more general review. So yes, this is a complete replacement and not a tweak here and a tweak there. I suppose you could ship both versions of the docs, but to date all users of the library have said that they prefer the newer version of the docs. The maintainer wants to hold the new documentation back because it doesn't document new features. I don't see why this is a reason to hold back the improved documentation for existing features. -- "The Direct3D Graphics Pipeline" free book http://tinyurl.com/d3d-pipeline The Computer Graphics Museum http://computergraphicsmuseum.org The Terminals Wiki http://terminals.classiccmp.org Legalize Adulthood! (my blog) http://legalizeadulthood.wordpress.com

Tim Blechmann writes:

gennadiy, from my understanding of the boost license, richard is free to fork boost.test and you have to right to forbid this ... if his design is better or worse or may or may not clash with boost.test is not your decision to do.

This is absolutly true. He is free to do whatever he wants. Whenther or not this should be part of the boost: I can express my opinion on this subject when time comes.

that said, i have no idea, why you strongly dislike richard's offer (and

Richard NEVER offered anything aside from "I can take over".

i don't care), but if you look for help ... what about taking advantage of the recent migration to git: anyone, including richard, could fix issues and submit pull requests. you just have to review the code and press a button. still you may want to close trac tickets if the bugs are fixed.

That will work for me fine. Short term I am looking for people to work with me on new documentation and pushing release out. Maintanence mode will come next. I have one person who expressed interest. We bothare busy professionals, so if anyone else is interested, you are still welcome to join ;) Gennadiy

"Vicente J. Botet Escriba" writes:

Le 20/01/14 20:40, Richard a écrit :

...

[Please do not mail me a copy of your followup]

I can take over the library. Hi Richard,

it is clear that you and Gennadiy will not work together on the same library.

What about forking the Boost.Test library into a new Boost.XTest with the contents of the Boost.Test release and your documentation and taking care of the issues associated to the release branch?

What the Boost community thinks about this proposition? Will competition between two libraries be a good thing for Boost?

While, on the one hand, it would make things so much easier, I'm not keen on this idea (though I'd enthusiatically join in if it went ahead). Gennadiy has created a technically excellent library. I'm even really excited about the new API that is waiting in the wings. The problem is not the code, but, rather, that Gennadiy is too close to his 'baby' to see it objectively from the perspective of its users. The excellent code is let down by: - documentation written for the implementor, not for the user - unfixed bugs (as Andrey pointed out, users couldn't care less if something is fixed in trunk) - communication - questions on the lists go unanswered for months Forking Boost.Test with different maintainers would resolve these flaws, but the new fork would be the same code + some bug fixes + readable documentation. That seems silly. Forks are usually for when developers want to take the _code_ in two incompatible directions. Alex -- Swish - Easy SFTP for Windows Explorer (http://www.swish-sftp.org)

Tim Blechmann writes:

...

- unfixed bugs (as Andrey pointed out, users couldn't care less if something is fixed in trunk)

even worse: for boost.heap i had some issues that due to a linking problem with boost.test all tests in the release branch failed, while they passed in trunk.

Was this a Boost.Test fault? Release version links fine as far as I know. Gennadiy