lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Joel Bernstein <>
Subject Re: Solr Ref Guide builds, precommit, and a plea
Date Thu, 10 May 2018 18:46:11 GMT
I see that the ref-guide build was also failing. When I made the first fix
to ref-guide build I didn't see any errors for a while figured that build
was now working. But then a new set of errors were generated. I didn't
realize that the ref-guide fails in stages.

I think in general I'm finding all the strictness in the refguide hard
figure out. Things like internal linking have taken a long time to get
right even though they work fine when viewed on github, the build often
still fails due to the links

Joel Bernstein

On Thu, May 10, 2018 at 2:33 PM, Joel Bernstein <> wrote:

> Ah, just saw all the errors caused by the refguide change that I made. I
> hadn't realized that precommit had been setup for refguide changes. I
> apologize for the noise this caused. I originally got one error reported
> for the ref guide build and fixed that one, and figured I was done. Next
> time I'll run precommit before pushing out ref guide changes.
> Joel Bernstein
> On Thu, May 10, 2018 at 10:30 AM, Cassandra Targett <>
> wrote:
>> There were some recent changes to the way the Solr Ref Guide gets built
>> made about a month ago, but stuff moves fast throughout the project so I
>> suspect it's likely a few have missed some details.
>> The first, and most important, change is now when you run "ant
>> precommit", internal (page to page) & javadoc links in the Ref Guide are
>> checked and validated. This used to only run when you specifically built
>> the Ref Guide - now it happens with precommit. This was all done with
>> SOLR-12134.
>> This means that if you didn't set up your env to build the HTML and you
>> don't want to build the PDF before editing docs, you don't have to. Run
>> precommit like you're already supposed to for every commit. It will fail if
>> your doc edits are messed up.
>> This was one step in the process of merging the Ref Guide build with the
>> main build. There's more to do, but I don't have a concrete plan in mind.
>> The second new thing that's worth mentioning is that the Ref Guide now
>> uses variables in place of "hard coded" version numbers for 3rd party
>> components. These variables pull their values from
>> so they are accurate for each release without human intervention. This
>> includes the versions of Tika, ZooKeeper, Log4J, OpenNLP, Velocity, Commons
>> Codec, and Dropwizard today - more can be added if they are needed.
>> Finally - and this likely applies to more than just the Ref Guide - let's
>> try to use branches for big stuff [1]. Branches are cheap and if things go
>> awry you don't stall everyone trying to use precommit for 12-18 hours or
>> more. We can set up Jenkins jobs for a branch if you want it, but master
>> really isn't the place for stuff that's not done yet, hasn't been tested
>> locally, and in a state where it's kinda broken, even if it's "just docs".
>> It also makes it easier for all of us to collaborate with each other, which
>> is never a bad thing.
>> Hope this info helps -
>> Cassandra
>> [1] And by big, I mean things on the order of adding an entire new
>> section of multiple new pages or reorganizing content in multiple pages,
>> particularly when you know it's going to take several weeks or months for
>> you to finally achieve your vision.

View raw message