lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Cassandra Targett <casstarg...@gmail.com>
Subject Re: Solr RefGuide Errata page wrong link
Date Thu, 10 May 2018 13:47:10 GMT
The Errata page isn't the place for "We released 7.3 and then found a bug"
IMO. There would be hundreds of candidates for that. SOLR-12321 isn't an
issue that we missed documenting - it was a bug that was not discovered
until later.

But you missed my point - if people have had ideas for how to use Errata
(or any similar page) but haven't ever done anything about it, are they
going to suddenly start? Maybe yesterday was the first time you personally
thought of anything to do with that page; that's fine, but my point is that
ideas are easy, actions are harder.

Let's understand up front that adding stuff to the Errata page would
require a re-release of the HTML version of the Ref Guide. This isn't that
hard and doesn't require a VOTE by design, but we have no process for it
yet.

The Errata page historically comes from the Confluence days and it made
much more sense then. We couldn't have versioned docs so we couldn't
re-release the Ref Guide if we found a glaring problem with the
documentation itself ("We said this feature does X, it really does Y"). We
could make live edits, though. But even then I remember *one* time that
someone used it.

Now if that happens we can re-release the Ref Guide. This has come up a
couple times when people thought about doing that. But once it was clear
they would need to be the ones to work through some decisions about how to
do it, the idea was abandoned.

Which proves my point - the idea of re-releasing the Ref Guide for any
reason is easy, but as soon as I say we don't already have all the details
worked out, it becomes harder and people move on. I'm really not trying to
bash anyone, it's just human nature and we're all juggling multiple
priorities. You can tell it hasn't reached the top of my list yet.

Major bugs found after release could be a very good thing to put in the Ref
Guide - I'd love it, really - but it would need some guidelines for what
goes there, and a process for updating and publishing the changes that
anyone can (and would) follow. I would advocate for changing the name of
the page in that case - "Issues Found After Release" would be better than
"Errata" - but that's ultimately only a tiny portion of the decisions that
would need to be made. The bigger questions are around how it gets from the
source code to the online site and *who* does that regularly IMO.

Maybe it's annoying that I keep bringing the conversation back to how we'll
do these things, but I'm a practical person by nature and my mind very
naturally jumps to figuring out obstacles to good ideas and trying to
understand what needs to happen to overcome them.

Cassandra

On Wed, May 9, 2018 at 5:57 PM Jan Høydahl <jan.asf@cominvent.com> wrote:

> One candidate for an errata entry could be
> https://issues.apache.org/jira/browse/SOLR-12321 do document that 7.3
> broke back compat with 7.2. This should normally have been documented in
> CHANGES Upgrade Notes.
>
> Perhaps there should be a link to the errata page from the top of
> CHANGES.txt, and from the beginning of the reference guide such as "About
> This Guide"?
>
> --
> Jan Høydahl, search solution architect
> Cominvent AS - www.cominvent.com
>
> 9. mai 2018 kl. 23:54 skrev Cassandra Targett <casstargett@gmail.com>:
>
> Yeah, you're right - it's parameterized using a bad parameter. I've often
> thought, though, that it should go away - we never update it and having a
> page that refers to itself online is weird. Thoughts? Anyone really want
> this page and intend to update it? I likely won't ever unless I get a ton
> of extra time somehow.
>
> As for the comments, I filed
> https://issues.apache.org/jira/browse/SOLR-12018 months ago.
>
> On Wed, May 9, 2018 at 2:51 PM Jan Høydahl <jan.asf@cominvent.com> wrote:
>
>> See https://lucene.apache.org/solr/guide/7_3/errata.html
>> The link on that page says /7.3/… but should be /7_3/… so it is a 404
>> now, and probably also in the PDF.
>>
>> PS: The Apache Comments section is not active
>>
>> --
>> Jan Høydahl, search solution architect
>> Cominvent AS - www.cominvent.com
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
>> For additional commands, e-mail: dev-help@lucene.apache.org
>>
>>
>

Mime
View raw message