You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lucene.apache.org by Jan Høydahl <ja...@cominvent.com> on 2018/05/09 19:51:31 UTC
Solr RefGuide Errata page wrong link
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
Re: Solr RefGuide Errata page wrong link
Posted by Jan Høydahl <ja...@cominvent.com>.
Do we have Google analytics stats for how often the Errata page in the online refGuide is visited? Eh, since the link from PDF is broken that number may be 0 :-)
I agree that most people may be unaware of that page, and perhaps the page is not needed since we tend to release new minor versions fairly often, so the amount of time the RefGuide is in error is low.
I also think that most people wanting to upgrade probably first check CHANGES.txt and may never consult the RefGuide, so even if we published some important info on that page it may not be read.
If we kill the whole concept of an Errata, perhaps we should simply direct users to https://lucene.apache.org/solr/news.html <https://lucene.apache.org/solr/news.html> where we announce releases and CVEs. And then if we wish to notify users about other critical flaws such as SOLR-12321, it is much easier to add a news entry to the page than to republish the guide?
--
Jan Høydahl, search solution architect
Cominvent AS - www.cominvent.com
> 10. mai 2018 kl. 15:47 skrev Cassandra Targett <ca...@gmail.com>:
>
> 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 <ma...@cominvent.com>> wrote:
> One candidate for an errata entry could be https://issues.apache.org/jira/browse/SOLR-12321 <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 <http://www.cominvent.com/>
>
>> 9. mai 2018 kl. 23:54 skrev Cassandra Targett <casstargett@gmail.com <ma...@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 <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 <ma...@cominvent.com>> wrote:
>> See https://lucene.apache.org/solr/guide/7_3/errata.html <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 <http://www.cominvent.com/>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org <ma...@lucene.apache.org>
>> For additional commands, e-mail: dev-help@lucene.apache.org <ma...@lucene.apache.org>
>>
>
Re: Solr RefGuide Errata page wrong link
Posted by Cassandra Targett <ca...@gmail.com>.
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 <ja...@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 <ca...@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 <ja...@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
>>
>>
>
Re: Solr RefGuide Errata page wrong link
Posted by Jan Høydahl <ja...@cominvent.com>.
One candidate for an errata entry could be https://issues.apache.org/jira/browse/SOLR-12321 <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 <ca...@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 <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 <ma...@cominvent.com>> wrote:
> See https://lucene.apache.org/solr/guide/7_3/errata.html <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 <http://www.cominvent.com/>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org <ma...@lucene.apache.org>
> For additional commands, e-mail: dev-help@lucene.apache.org <ma...@lucene.apache.org>
>
Re: Solr RefGuide Errata page wrong link
Posted by Cassandra Targett <ca...@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 <ja...@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
>
>