lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Joel Bernstein <joels...@gmail.com>
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
http://joelsolr.blogspot.com/

On Thu, May 10, 2018 at 2:33 PM, Joel Bernstein <joelsolr@gmail.com> 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
> http://joelsolr.blogspot.com/
>
> On Thu, May 10, 2018 at 10:30 AM, Cassandra Targett <ctargett@apache.org>
> 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 ivy-versions.properties
>> 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.
>>
>
>

Mime
View raw message