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

Subject: Re: [boost] [GSoC] [Boost.Hana] Formal review request
From: Niall Douglas (s_sourceforge_at_[hidden])
Date: 2014-07-30 09:50:35

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.

Niall

-- 
ned Productions Limited Consulting
http://www.nedproductions.biz/ 
http://ie.linkedin.com/in/nialldouglas/