You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lucene.apache.org by Cassandra Targett <ca...@gmail.com> on 2019/10/23 17:53:05 UTC
Re: Rethinking how we publish the Solr Ref Guide
FYI, bumping this - I’m about to send a mail to the user list explaining why we’ve stopped releasing the PDF.
I think I said originally we’d publish the 8.2 PDF, but I’ve changed my mind on that and edited the Ref Guide landing page to include 8.2 and indicate it is HTML only starting with 8.2.
If there is an outcry in the community about the change, we can discuss other options depending on the feedback.
Cassandra
On Sep 23, 2019, 9:54 AM -0500, Jason Gerlowski <ge...@gmail.com>, wrote:
> +1. That all sounds good to me. Excited to see some streamlining here.
>
> On Fri, Sep 20, 2019 at 3:46 PM Cassandra Targett <ca...@gmail.com> wrote:
> >
> > Thanks everyone, by the way, for the encouragement and feedback here.
> >
> > For next steps, how do folks feel about making the change to stop voting on the PDF *now*? Or, I guess, retroactively for 8.2 since that’s not out yet. I could push the HTML and make a PDF but announce to the list that from 8.2 forward we consider the HTML the main Ref Guide and the PDF is “for convenience” (and explain the thinking behind it).
> >
> > If we want a VOTE on this policy change, I can do that - I feel like we have consensus without it, but we could be more formal about it if folks prefer.
> >
> > For 8.3 we'll see what we can get automated there, but if it’s not ready I’ll just do it manually once the RC is out.
> >
> > I’ll file a Jira for some of the changes I’ll make to the docs for the process, etc., and another one for automation ideas.
> >
> > Cassandra
> > On Sep 19, 2019, 2:53 PM -0500, Noble Paul <no...@gmail.com>, wrote:
> >
> > First of all a big thanks to Cassandra to help coordinate and build
> > our ref guide to make it professional. It really used to be pathetic
> > before you took over
> >
> > . Yes we need to avoid "creating work" . There should be no need for a
> > ref guide release.
> >
> > +1 for your plan
> >
> > On Thu, Sep 19, 2019 at 11:57 PM Cassandra Targett
> > <ca...@gmail.com> wrote:
> >
> >
> > The pages do already have a “Site last generated” date on them at the bottom. It’s specifically worded that way for a reason.
> >
> > We actually wanted the date the .adoc file was last updated to be in the footer too, but the problem has always been that a static site generator always regenerates all pages every time - so every single page, edited or not, always has the same exact date on it.
> >
> > And, our build works by copying everything under `solr/solr-ref-guide/src` to `solr/build`, so every file really has a create date and last updated date that are always the date you do the build. Basically, the files you see and work with are not actually the same files that get built - we build from copies that are made at build-time.
> >
> > (That’s all why it says “Site last generated” instead of “Last updated”.)
> >
> > I’m not saying there’s no way to add a last updated date for the underlying file, it’s just not obvious how to do it so we skipped it.
> >
> > No problem, though, adding a link to Github - that’s actually kind of a different thing and I’m pretty sure we could do that right now.
> >
> > Cassandra
> > On Sep 19, 2019, 7:07 AM -0500, Anshum Gupta <an...@anshumgupta.net>, wrote:
> >
> > I agree that we should be able to fix mistakes, my only suggestion was that those mistakes not be non-trivial. But the more I think about it, the more I feel convinced about just publishing the updates - however, having a time stamp on when the guide was last updated would be nice to have. Anything else would require much more effort and I'm not sure it's worth it.
> >
> > On Wed, Sep 18, 2019 at 2:48 PM Chris Hostetter <ho...@fucit.org> wrote:
> >
> >
> >
> > : > However Anshum does make a good point that users wouldn't know when
> > : the pages have changed. I think it would be great to have a link on each
> > : ref-guide page that shows the last modified date and links to the
> > : history of that page in github
> >
> > : Perhaps we could instead provide a single HTML page or HTML table as
> > : part of or alongside each guide, showing all commits touching the guide
> > : on that branch after the release. Could probably be baked in as part of
> > : the release script. Using the release date or git hash for the release,
> >
> > Yeah, there are a lot of options we could pursue for generating a
> > "changes" list as part of an automated build process -- but i would
> > consider this idea a "nice to have" feature that shouldn't block moving
> > forward.
> >
> > Given 2 options, I would much rather:
> > a) have the ability to quickly/easily "fix" mistakes/ommisions in
> > "official X.y ref-guide" on our site and have it automatically republish,
> > w/o it being immediately obvious to users that a page may have changed
> > between yesterday and today.
> > ... over ...
> > b) *NOT* being able to re-publish at all just for the sake of users
> > knowing that the (incorrect) content they are reading is consistent
> > between yesterday and today.
> >
> >
> > -Hoss
> > http://www.lucidworks.com/
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
> > For additional commands, e-mail: dev-help@lucene.apache.org
> >
> >
> >
> > --
> > Anshum Gupta
> >
> >
> >
> >
> > --
> > -----------------------------------------------------
> > Noble Paul
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
> > For additional commands, e-mail: dev-help@lucene.apache.org
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: dev-help@lucene.apache.org
>
Re: Rethinking how we publish the Solr Ref Guide
Posted by Gézapeti <ge...@gmail.com>.
Thanks for the help! The link was an internal documentation I assumed it
was correct. I've updated it in our wiki page.
On Mon, Oct 28, 2019 at 7:57 PM Cassandra Targett <ca...@gmail.com>
wrote:
> Yes, it does need to be updated. I was waiting to do that until I informed
> the user list about the change to not publish a PDF any longer which I’m
> ready to send now, so I’ll also fix the redirect link.
>
> Cassandra
> On Oct 28, 2019, 12:23 PM -0500, Gus Heck <gu...@gmail.com>, wrote:
>
> Ah yes I assumed that the original link had come from a good source...
> OTOH
> https://lucene.apache.org/solr/guide/field-types-included-with-solr.html still
> needs to be updated to point to 8_2 I think.
>
> On Mon, Oct 28, 2019 at 1:01 PM Chris Hostetter <ho...@fucit.org>
> wrote:
>
>>
>> : The redirection is wrong, if you remove "latest" from the urls with 8_1
>> in
>>
>> The "redirection" rules appear to be working as designed -- but AFAIK they
>> were never designed with any idea of having a "latest/" path.
>>
>> the Latest URL has no is just the page name w/o a version number, not the
>> page name prefixed with "latest/".
>>
>> Specifically this is suppose to be the "latest" URL for the page in
>> question...
>>
>> https://lucene.apache.org/solr/guide/field-types-included-with-solr.html
>>
>> : > I was trying to access
>> : >
>> https://lucene.apache.org/solr/guide/latest/field-types-included-with-solr.html
>>
>> ...where did you find that link?
>>
>> I'm pretty sure the place that linked to that URL is the place that has a
>> mistake.
>>
>>
>>
>> -Hoss
>> http://www.lucidworks.com/
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
>> For additional commands, e-mail: dev-help@lucene.apache.org
>>
>>
>
> --
> http://www.needhamsoftware.com (work)
> http://www.the111shift.com (play)
>
>
Re: Rethinking how we publish the Solr Ref Guide
Posted by Cassandra Targett <ca...@gmail.com>.
Yes, it does need to be updated. I was waiting to do that until I informed the user list about the change to not publish a PDF any longer which I’m ready to send now, so I’ll also fix the redirect link.
Cassandra
On Oct 28, 2019, 12:23 PM -0500, Gus Heck <gu...@gmail.com>, wrote:
> Ah yes I assumed that the original link had come from a good source... OTOH https://lucene.apache.org/solr/guide/field-types-included-with-solr.html still needs to be updated to point to 8_2 I think.
>
> > On Mon, Oct 28, 2019 at 1:01 PM Chris Hostetter <ho...@fucit.org> wrote:
> > >
> > > : The redirection is wrong, if you remove "latest" from the urls with 8_1 in
> > >
> > > The "redirection" rules appear to be working as designed -- but AFAIK they
> > > were never designed with any idea of having a "latest/" path.
> > >
> > > the Latest URL has no is just the page name w/o a version number, not the
> > > page name prefixed with "latest/".
> > >
> > > Specifically this is suppose to be the "latest" URL for the page in
> > > question...
> > >
> > > https://lucene.apache.org/solr/guide/field-types-included-with-solr.html
> > >
> > > : > I was trying to access
> > > : > https://lucene.apache.org/solr/guide/latest/field-types-included-with-solr.html
> > >
> > > ...where did you find that link?
> > >
> > > I'm pretty sure the place that linked to that URL is the place that has a
> > > mistake.
> > >
> > >
> > >
> > > -Hoss
> > > http://www.lucidworks.com/
> > >
> > > ---------------------------------------------------------------------
> > > To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
> > > For additional commands, e-mail: dev-help@lucene.apache.org
> > >
>
>
> --
> http://www.needhamsoftware.com (work)
> http://www.the111shift.com (play)
Re: Rethinking how we publish the Solr Ref Guide
Posted by Gus Heck <gu...@gmail.com>.
Ah yes I assumed that the original link had come from a good source... OTOH
https://lucene.apache.org/solr/guide/field-types-included-with-solr.html still
needs to be updated to point to 8_2 I think.
On Mon, Oct 28, 2019 at 1:01 PM Chris Hostetter <ho...@fucit.org>
wrote:
>
> : The redirection is wrong, if you remove "latest" from the urls with 8_1
> in
>
> The "redirection" rules appear to be working as designed -- but AFAIK they
> were never designed with any idea of having a "latest/" path.
>
> the Latest URL has no is just the page name w/o a version number, not the
> page name prefixed with "latest/".
>
> Specifically this is suppose to be the "latest" URL for the page in
> question...
>
> https://lucene.apache.org/solr/guide/field-types-included-with-solr.html
>
> : > I was trying to access
> : >
> https://lucene.apache.org/solr/guide/latest/field-types-included-with-solr.html
>
> ...where did you find that link?
>
> I'm pretty sure the place that linked to that URL is the place that has a
> mistake.
>
>
>
> -Hoss
> http://www.lucidworks.com/
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: dev-help@lucene.apache.org
>
>
--
http://www.needhamsoftware.com (work)
http://www.the111shift.com (play)
Re: Rethinking how we publish the Solr Ref Guide
Posted by Chris Hostetter <ho...@fucit.org>.
: The redirection is wrong, if you remove "latest" from the urls with 8_1 in
The "redirection" rules appear to be working as designed -- but AFAIK they
were never designed with any idea of having a "latest/" path.
the Latest URL has no is just the page name w/o a version number, not the
page name prefixed with "latest/".
Specifically this is suppose to be the "latest" URL for the page in
question...
https://lucene.apache.org/solr/guide/field-types-included-with-solr.html
: > I was trying to access
: > https://lucene.apache.org/solr/guide/latest/field-types-included-with-solr.html
...where did you find that link?
I'm pretty sure the place that linked to that URL is the place that has a
mistake.
-Hoss
http://www.lucidworks.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org
Re: Rethinking how we publish the Solr Ref Guide
Posted by Gus Heck <gu...@gmail.com>.
The redirection is wrong, if you remove "latest" from the urls with 8_1 in
them it looks like you get the right page. Also, 8_2 is the latest now so
these are also out of date I think.
On Mon, Oct 28, 2019 at 10:24 AM Gézapeti <ge...@gmail.com> wrote:
> Hi everyone,
>
> I was trying to access
> https://lucene.apache.org/solr/guide/latest/field-types-included-with-solr.html
> and it got redirected to
> https://lucene.apache.org/solr/guide/8_1/latest/field-types-included-with-solr.html
> which is a 404.
> I've tested https://lucene.apache.org/solr/guide/latest/ and it also
> redirects to https://lucene.apache.org/solr/guide/8_1/latest/
> I could not find the reference for this in the ref-guide project.
> Can someone fix it or point me in the right direction to fix the issue?
> Thanks
> gp
>
> On Wed, Oct 23, 2019 at 7:53 PM Cassandra Targett <ca...@gmail.com>
> wrote:
>
>> FYI, bumping this - I’m about to send a mail to the user list explaining
>> why we’ve stopped releasing the PDF.
>>
>> I think I said originally we’d publish the 8.2 PDF, but I’ve changed my
>> mind on that and edited the Ref Guide landing page to include 8.2 and
>> indicate it is HTML only starting with 8.2.
>>
>> If there is an outcry in the community about the change, we can discuss
>> other options depending on the feedback.
>>
>> Cassandra
>> On Sep 23, 2019, 9:54 AM -0500, Jason Gerlowski <ge...@gmail.com>,
>> wrote:
>>
>> +1. That all sounds good to me. Excited to see some streamlining here.
>>
>> On Fri, Sep 20, 2019 at 3:46 PM Cassandra Targett <ca...@gmail.com>
>> wrote:
>>
>>
>> Thanks everyone, by the way, for the encouragement and feedback here.
>>
>> For next steps, how do folks feel about making the change to stop voting
>> on the PDF *now*? Or, I guess, retroactively for 8.2 since that’s not out
>> yet. I could push the HTML and make a PDF but announce to the list that
>> from 8.2 forward we consider the HTML the main Ref Guide and the PDF is
>> “for convenience” (and explain the thinking behind it).
>>
>> If we want a VOTE on this policy change, I can do that - I feel like we
>> have consensus without it, but we could be more formal about it if folks
>> prefer.
>>
>> For 8.3 we'll see what we can get automated there, but if it’s not ready
>> I’ll just do it manually once the RC is out.
>>
>> I’ll file a Jira for some of the changes I’ll make to the docs for the
>> process, etc., and another one for automation ideas.
>>
>> Cassandra
>> On Sep 19, 2019, 2:53 PM -0500, Noble Paul <no...@gmail.com>, wrote:
>>
>> First of all a big thanks to Cassandra to help coordinate and build
>> our ref guide to make it professional. It really used to be pathetic
>> before you took over
>>
>> . Yes we need to avoid "creating work" . There should be no need for a
>> ref guide release.
>>
>> +1 for your plan
>>
>> On Thu, Sep 19, 2019 at 11:57 PM Cassandra Targett
>> <ca...@gmail.com> wrote:
>>
>>
>> The pages do already have a “Site last generated” date on them at the
>> bottom. It’s specifically worded that way for a reason.
>>
>> We actually wanted the date the .adoc file was last updated to be in the
>> footer too, but the problem has always been that a static site generator
>> always regenerates all pages every time - so every single page, edited or
>> not, always has the same exact date on it.
>>
>> And, our build works by copying everything under
>> `solr/solr-ref-guide/src` to `solr/build`, so every file really has a
>> create date and last updated date that are always the date you do the
>> build. Basically, the files you see and work with are not actually the same
>> files that get built - we build from copies that are made at build-time.
>>
>> (That’s all why it says “Site last generated” instead of “Last updated”.)
>>
>> I’m not saying there’s no way to add a last updated date for the
>> underlying file, it’s just not obvious how to do it so we skipped it.
>>
>> No problem, though, adding a link to Github - that’s actually kind of a
>> different thing and I’m pretty sure we could do that right now.
>>
>> Cassandra
>> On Sep 19, 2019, 7:07 AM -0500, Anshum Gupta <an...@anshumgupta.net>,
>> wrote:
>>
>> I agree that we should be able to fix mistakes, my only suggestion was
>> that those mistakes not be non-trivial. But the more I think about it, the
>> more I feel convinced about just publishing the updates - however, having a
>> time stamp on when the guide was last updated would be nice to have.
>> Anything else would require much more effort and I'm not sure it's worth it.
>>
>> On Wed, Sep 18, 2019 at 2:48 PM Chris Hostetter <ho...@fucit.org>
>> wrote:
>>
>>
>>
>> : > However Anshum does make a good point that users wouldn't know when
>> : the pages have changed. I think it would be great to have a link on each
>> : ref-guide page that shows the last modified date and links to the
>> : history of that page in github
>>
>> : Perhaps we could instead provide a single HTML page or HTML table as
>> : part of or alongside each guide, showing all commits touching the guide
>> : on that branch after the release. Could probably be baked in as part of
>> : the release script. Using the release date or git hash for the release,
>>
>> Yeah, there are a lot of options we could pursue for generating a
>> "changes" list as part of an automated build process -- but i would
>> consider this idea a "nice to have" feature that shouldn't block moving
>> forward.
>>
>> Given 2 options, I would much rather:
>> a) have the ability to quickly/easily "fix" mistakes/ommisions in
>> "official X.y ref-guide" on our site and have it automatically republish,
>> w/o it being immediately obvious to users that a page may have changed
>> between yesterday and today.
>> ... over ...
>> b) *NOT* being able to re-publish at all just for the sake of users
>> knowing that the (incorrect) content they are reading is consistent
>> between yesterday and today.
>>
>>
>> -Hoss
>> http://www.lucidworks.com/
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
>> For additional commands, e-mail: dev-help@lucene.apache.org
>>
>>
>>
>> --
>> Anshum Gupta
>>
>>
>>
>>
>> --
>> -----------------------------------------------------
>> Noble Paul
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
>> For additional commands, e-mail: dev-help@lucene.apache.org
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
>> For additional commands, e-mail: dev-help@lucene.apache.org
>>
>>
--
http://www.needhamsoftware.com (work)
http://www.the111shift.com (play)
Re: Rethinking how we publish the Solr Ref Guide
Posted by Gézapeti <ge...@gmail.com>.
Hi everyone,
I was trying to access
https://lucene.apache.org/solr/guide/latest/field-types-included-with-solr.html
and it got redirected to
https://lucene.apache.org/solr/guide/8_1/latest/field-types-included-with-solr.html
which is a 404.
I've tested https://lucene.apache.org/solr/guide/latest/ and it also
redirects to https://lucene.apache.org/solr/guide/8_1/latest/
I could not find the reference for this in the ref-guide project.
Can someone fix it or point me in the right direction to fix the issue?
Thanks
gp
On Wed, Oct 23, 2019 at 7:53 PM Cassandra Targett <ca...@gmail.com>
wrote:
> FYI, bumping this - I’m about to send a mail to the user list explaining
> why we’ve stopped releasing the PDF.
>
> I think I said originally we’d publish the 8.2 PDF, but I’ve changed my
> mind on that and edited the Ref Guide landing page to include 8.2 and
> indicate it is HTML only starting with 8.2.
>
> If there is an outcry in the community about the change, we can discuss
> other options depending on the feedback.
>
> Cassandra
> On Sep 23, 2019, 9:54 AM -0500, Jason Gerlowski <ge...@gmail.com>,
> wrote:
>
> +1. That all sounds good to me. Excited to see some streamlining here.
>
> On Fri, Sep 20, 2019 at 3:46 PM Cassandra Targett <ca...@gmail.com>
> wrote:
>
>
> Thanks everyone, by the way, for the encouragement and feedback here.
>
> For next steps, how do folks feel about making the change to stop voting
> on the PDF *now*? Or, I guess, retroactively for 8.2 since that’s not out
> yet. I could push the HTML and make a PDF but announce to the list that
> from 8.2 forward we consider the HTML the main Ref Guide and the PDF is
> “for convenience” (and explain the thinking behind it).
>
> If we want a VOTE on this policy change, I can do that - I feel like we
> have consensus without it, but we could be more formal about it if folks
> prefer.
>
> For 8.3 we'll see what we can get automated there, but if it’s not ready
> I’ll just do it manually once the RC is out.
>
> I’ll file a Jira for some of the changes I’ll make to the docs for the
> process, etc., and another one for automation ideas.
>
> Cassandra
> On Sep 19, 2019, 2:53 PM -0500, Noble Paul <no...@gmail.com>, wrote:
>
> First of all a big thanks to Cassandra to help coordinate and build
> our ref guide to make it professional. It really used to be pathetic
> before you took over
>
> . Yes we need to avoid "creating work" . There should be no need for a
> ref guide release.
>
> +1 for your plan
>
> On Thu, Sep 19, 2019 at 11:57 PM Cassandra Targett
> <ca...@gmail.com> wrote:
>
>
> The pages do already have a “Site last generated” date on them at the
> bottom. It’s specifically worded that way for a reason.
>
> We actually wanted the date the .adoc file was last updated to be in the
> footer too, but the problem has always been that a static site generator
> always regenerates all pages every time - so every single page, edited or
> not, always has the same exact date on it.
>
> And, our build works by copying everything under `solr/solr-ref-guide/src`
> to `solr/build`, so every file really has a create date and last updated
> date that are always the date you do the build. Basically, the files you
> see and work with are not actually the same files that get built - we build
> from copies that are made at build-time.
>
> (That’s all why it says “Site last generated” instead of “Last updated”.)
>
> I’m not saying there’s no way to add a last updated date for the
> underlying file, it’s just not obvious how to do it so we skipped it.
>
> No problem, though, adding a link to Github - that’s actually kind of a
> different thing and I’m pretty sure we could do that right now.
>
> Cassandra
> On Sep 19, 2019, 7:07 AM -0500, Anshum Gupta <an...@anshumgupta.net>,
> wrote:
>
> I agree that we should be able to fix mistakes, my only suggestion was
> that those mistakes not be non-trivial. But the more I think about it, the
> more I feel convinced about just publishing the updates - however, having a
> time stamp on when the guide was last updated would be nice to have.
> Anything else would require much more effort and I'm not sure it's worth it.
>
> On Wed, Sep 18, 2019 at 2:48 PM Chris Hostetter <ho...@fucit.org>
> wrote:
>
>
>
> : > However Anshum does make a good point that users wouldn't know when
> : the pages have changed. I think it would be great to have a link on each
> : ref-guide page that shows the last modified date and links to the
> : history of that page in github
>
> : Perhaps we could instead provide a single HTML page or HTML table as
> : part of or alongside each guide, showing all commits touching the guide
> : on that branch after the release. Could probably be baked in as part of
> : the release script. Using the release date or git hash for the release,
>
> Yeah, there are a lot of options we could pursue for generating a
> "changes" list as part of an automated build process -- but i would
> consider this idea a "nice to have" feature that shouldn't block moving
> forward.
>
> Given 2 options, I would much rather:
> a) have the ability to quickly/easily "fix" mistakes/ommisions in
> "official X.y ref-guide" on our site and have it automatically republish,
> w/o it being immediately obvious to users that a page may have changed
> between yesterday and today.
> ... over ...
> b) *NOT* being able to re-publish at all just for the sake of users
> knowing that the (incorrect) content they are reading is consistent
> between yesterday and today.
>
>
> -Hoss
> http://www.lucidworks.com/
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: dev-help@lucene.apache.org
>
>
>
> --
> Anshum Gupta
>
>
>
>
> --
> -----------------------------------------------------
> Noble Paul
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: dev-help@lucene.apache.org
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: dev-help@lucene.apache.org
>
>