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:33:32 GMT
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 <>

> 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