Re: [boost] [GSoC] [Boost.Hana] Formal review request

Subject: Re: [boost] [GSoC] [Boost.Hana] Formal review request
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2014-07-30 12:22:17

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Niall Douglas
> Sent: 30 July 2014 14:51
> To: boost_at_[hidden]
> Subject: Re: [boost] [GSoC] [Boost.Hana] Formal review request
> 
> On 29 Jul 2014 at 19:13, louis_dionne wrote:
> 
> > > No, it's easier than you think. Have a look at
> > > https://ci.nedprod.com/ whose default dashboard shows a graph
> > > labelled "RUDP performance". This tracks performance of a build over
> > > time to ensure performance doesn't regress. All you need is for your
> > > performance test tool to output some CSV, a Jenkins Plot plugin does
> > > the rest.
> >
> > That's pretty cool!
> 
> I'm getting ever keener on traffic light dashboards the older I become,
probably due
> to failing memory :). The dashboard at https://ci.nedprod.com/view/Boost.AFIO/
> tells me everything I need to know about the present state of AFIO.
> 
> > > Mastering Jenkins takes months, but once mastered configuring all
> > > sorts of test scenarios becomes trivial. I'd actively merge your
> > > Jenkins/Travis output into your docs too, it is nowadays an online
> > > world.
> >
> > I don't have months, but if someone is willing to help I'll
> > collaborate. The current build system is setup with CMake; surely it
> > integrates easily with Jenkins?
> 
> Indeed it does, but you've just raised another likely problem for peer review.
Some
> will argue that you need to use Boost.Build throughout. It's a bit like the
BoostBook
> docs here, it's about ticking off boxes.
> 
> Regarding modern CI testing for Boost, well there isn't any, you're expected
to
> provide your own. Travis is clunky, limited but free, either myself or Antony
can help
> you with that. Jenkins is vastly more powerful, but you'll need a machine
> permanently visible to the internet for maximum usefulness. If you're planning
to
> stay in software development for the next few years, you'll find the effort in
setting
> up a personal Jenkins install easily repays in productivity and an enormous
> improvement in the quality of code you ship (tip: start with a hypervisor
platform on
> a dedicated machine, it'll save you tons of time during upgrades later. I
personally
> use a Linux distro called Proxmox, it makes managing VMs easy). For example, I
am
> for my day job tracking down a timing bug which occurs less than 4% of the
time, to
> find it I have Jenkins run a soak test every ten minutes and filter out when
it fails.
> 
> Jenkins is enormously capable and flexible, but is also a badly designed piece
of
> software with a very non-obviously steep learning curve and a
counter-intuitive UI.
> Once you have learned all the stuff they don't document, it's great. For
example, all
> those Boost.AFIO per-target jobs listed at the dashboard above are all
automagically
> generated for me and the VM targets are orchestrated via managed scripts, I
> originally made the naïve mistake most make of manually configuring separate
jobs
> and then the next most-naive mistake of thinking the matrix builder is
actually useful
> and not horrendously broken.
> 
> > > As you'll find when formal review comes, to pass isn't about how
> > > good your library is, it's about eliminating as many rational
> > > objections others can think of.
> >
> > I hope it's at least _a bit_ about how good the library is. :)
> 
> It's very similar in practice to peer review for academic papers at the top
journals.
> Yes, it does have something to do with quality, but fashionable topics plays a
big
> part, as does current research funding imperatives, as does ticking many
invisible
> cultural boxes you only know about with experience, as does a bit of luck in
which
> reviewers you get and the mood they are in. You've got the fashionable topics
part
> in spades at least.
> 
> > > Besides, you'll invest five days or so of wishing pain on those
> > > responsible for the tools, and once it's working you'll never need
> > > touch it again. I did find it took some months to find and fix all
> > > the corner cases in the doc output though, and even now PDF
> > > generation from AFIO's docs are a joke due to the long template
> > > strings.
> >
> > If I spend 5 days on improving the current documentation, I'll have
> > the best freakin' documentation you could ever wish to have in Boost.
> > I'll favor doing that before BoostBook, and hopefully the quality of
> > the resulting documentation clears up a lot of objections.
> 
> The tools for converting doxygen to BoostBook only do reasonably well with
> reference documentation. They do a poor job with explanatory sections or
tutorials.
> For those you'll have to manually rewrite doxygen markup probably into
quickbook
> markup.

For those libraries that use the Quickbook/Doxygen/Autoindex toolchain, it is
assumed that Quickbook is used for the tutorial part.

For me, the killer argument for using Quickbook is the ability to use *code
snippets*.
These ensure that the bits of code you show have actually been through the
(current) compiler.

I see no problems converting to Quickbook. Conversion is not too painful -
especially if you have done it before.

However, I don't think you should worry about the docs now - they are fine for a
review.

IMO your priority is to get some real-life users able to make an informed
review.

Paul

PS For me, the library name is a big turn off - it doesn't say what the library
does.

And, for me, the names of functions are enough to condemn the library as
unacceptable for Boost. 

This really, really impressive and obviously really useful library is for C++
users, not Haskell users.

---
Paul A. Bristow
Prizet Farmhouse
Kendal UK LA8 8AB
[phone]