lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Cassandra Targett <>
Subject Solr Ref Guide builds, precommit, and a plea
Date Thu, 10 May 2018 14:30:25 GMT
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 -

[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