I restored the Solr 3.6.0 javadocs at <http://lucene.apache.org/solr/api-3_6_0/>:

- Added line "solr/api-3_6_0" to extpaths.txt on the CMS source tree.

- Restored and renamed the javadocs directory:

svn -m "bring Solr 3.6.0 javadocs back to life" copy \
https://svn.apache.org/repos/infra/websites/production/lucene/content/solr/api@824226 \
https://svn.apache.org/repos/infra/websites/production/lucene/content/solr/api-3_6_0

Steve

-----Original Message-----
From: Robert Muir [mailto:[EMAIL PROTECTED]]
Sent: Tuesday, July 03, 2012 4:22 PM
To: [EMAIL PROTECTED]
Subject: Re: Solr 3.6.0 javadocs are missing from the site

On Tue, Jul 3, 2012 at 4:16 PM, Chris Hostetter <[EMAIL PROTECTED]> wrote:
>
> just brought this up on #lucene-dev .. the SOlr 3.6.0 javadocs are
> gone from the site, and all javadoc URLs were broken as a result

they aren't broken: i fixed all these api/ links across the website.
where is a broken link?

> past discussion when we switched to the cms and then released 3.6 was
> that we would start versioning the solr javadocs just like the
> lucene-core

-1 to the Release Manager doing refactoring on the website. RM does releasing. If people want to refactor things from unversioned to versioned, do that separately please. RM already has enough to do.

> javadocs, and have both the latest 3.6.X and 4.X versions on the site
> at distinct urls -- the goal being that
> "http://lucene.staging.apache.org/solr/api" could always redirect to
> the latest.

I don't like that: lucene doesnt need this. why does solr?

--
lucidimagination.com

---------------------------------------------------------------------

: > just brought this up on #lucene-dev .. the SOlr 3.6.0 javadocs are gone from
: > the site, and all javadoc URLs were broken as a result
:
: they aren't broken: i fixed all these api/ links across the website.
: where is a broken link?

Until i added the redirect in .htaccess (so they would start pointing to
hte 4.0-alpha docs), java URLs like this one (from google, the wiki,
bookmarks, blogs, etc...) were all broken...

http://lucene.apache.org/solr/api/org/apache/solr/schema/ExternalFileField.html

: > past discussion when we switched to the cms and then released 3.6 was that
: > we would start versioning the solr javadocs just like the lucene-core
:
: -1 to the Release Manager doing refactoring on the website. RM does
: releasing. If people want to refactor things from unversioned to
: versioned, do that separately please. RM already has enough to do.

Who the fuck said anything about expecting the RM to refactor the website?

i didnt expect you to do anything special with the javadocs, just
upload the new ones (which i know was a big ass fucking pain and i
appreciate how much time/effort you put into dealing with it) and then
other people (like me) could volunteer to add markdown pages, fix links,
etc...

if it really bothered you that the 3.6.0 javadocs were using the url
"/solr/api" and you wanted them to be something else that's fine, you
could have done an "svn mv" at anytime -- that didn't have to be something
you took it upon yourself to do as the release manager.  

My concerns are/were simply:

a) the solr 3.6 javadocs should still be online at some path for the
forseeable future -- just like hte lucene-core 3.6 javadocs are.

b) we shouldn't break existing URLs -- since the "/solr/api/..."
URLs have been arround for a long time, and are linked to from lots
of places, we should do what we can to make sure they always redirect to
somewhere useful.

I'm happy to deal with all of this, i'm just asking folks to not delete
valid and useful docs fro mthe website.  if you don't like the URL/path,
then move them, but please don't delete them.

: > javadocs, and have both the latest 3.6.X and 4.X versions on the site at
: > distinct urls -- the goal being that
: > "http://lucene.staging.apache.org/solr/api" could always redirect to the
: > latest.
:
: I don't like that: lucene doesnt need this. why does solr?

Because the URL has always existed and people use it.  it needs to
point/redirect somwhere, and it's trivial (by editing .htaccess) for it to
point to the "most revent" version, so we might as well to that.

-Hoss

---------------------------------------------------------------------

my problem is the unversioned url. with this links break, but in subtle
ways. another horrible example of this is old news blurbs for previous
releases, because they use an unversioned redirect url so they go to the
wrong place. that's why I removed old news blurbs.

these unversioned links should die, die, die. but can we compromise here?
instead can we have api-3 and api-4, etc. we realize some external links
could still break, but given our back compat policy it should be rare...
On Jul 3, 2012 5:58 PM, "Chris Hostetter" <[EMAIL PROTECTED]> wrote:

> : > just brought this up on #lucene-dev .. the SOlr 3.6.0 javadocs are
> gone from
> : > the site, and all javadoc URLs were broken as a result
> :
> : they aren't broken: i fixed all these api/ links across the website.
> : where is a broken link?
>
> Until i added the redirect in .htaccess (so they would start pointing to
> hte 4.0-alpha docs), java URLs like this one (from google, the wiki,
> bookmarks, blogs, etc...) were all broken...
>
>
> http://lucene.apache.org/solr/api/org/apache/solr/schema/ExternalFileField.html
>
> : > past discussion when we switched to the cms and then released 3.6 was
> that
> : > we would start versioning the solr javadocs just like the lucene-core
> :
> : -1 to the Release Manager doing refactoring on the website. RM does
> : releasing. If people want to refactor things from unversioned to
> : versioned, do that separately please. RM already has enough to do.
>
> Who the fuck said anything about expecting the RM to refactor the website?
>
> i didnt expect you to do anything special with the javadocs, just
> upload the new ones (which i know was a big ass fucking pain and i
> appreciate how much time/effort you put into dealing with it) and then
> other people (like me) could volunteer to add markdown pages, fix links,
> etc...
>
> if it really bothered you that the 3.6.0 javadocs were using the url
> "/solr/api" and you wanted them to be something else that's fine, you
> could have done an "svn mv" at anytime -- that didn't have to be something
> you took it upon yourself to do as the release manager.
>
> My concerns are/were simply:
>
> a) the solr 3.6 javadocs should still be online at some path for the
> forseeable future -- just like hte lucene-core 3.6 javadocs are.
>
> b) we shouldn't break existing URLs -- since the "/solr/api/..."
> URLs have been arround for a long time, and are linked to from lots
> of places, we should do what we can to make sure they always redirect to
> somewhere useful.
>
> I'm happy to deal with all of this, i'm just asking folks to not delete
> valid and useful docs fro mthe website.  if you don't like the URL/path,
> then move them, but please don't delete them.
>
> : > javadocs, and have both the latest 3.6.X and 4.X versions on the site
> at
> : > distinct urls -- the goal being that
> : > "http://lucene.staging.apache.org/solr/api" could always redirect to
> the
> : > latest.
> :
> : I don't like that: lucene doesnt need this. why does solr?
>
> Because the URL has always existed and people use it.  it needs to
> point/redirect somwhere, and it's trivial (by editing .htaccess) for it to
> point to the "most revent" version, so we might as well to that.
>
> -Hoss
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [EMAIL PROTECTED]
> For additional commands, e-mail: [EMAIL PROTECTED]
>
>

: these unversioned links should die, die, die. but can we compromise here?
: instead can we have api-3 and api-4, etc. we realize some external links
: could still break, but given our back compat policy it should be rare...

that's exactly what i'm saying .. sarowe alredy put the 3.x javadocs back
on the site using "api-3_..." i'm just fixing up a few places to link to
them where appropate.

but anyone who has old bookmarked links to "/solr/api/..." should have
those links go somwhere as long as the classes still exist (also already
fixed)
-Hoss

---------------------------------------------------------------------

that's not what I mean. api/ should die. but I'm ok with api-3 that points
to 3.6.0 and so on as the links should never disappear within a major
release (except heavy breaks)
On Jul 3, 2012 6:19 PM, "Chris Hostetter" <[EMAIL PROTECTED]> wrote:

>
> : these unversioned links should die, die, die. but can we compromise here?
> : instead can we have api-3 and api-4, etc. we realize some external links
> : could still break, but given our back compat policy it should be rare...
>
> that's exactly what i'm saying .. sarowe alredy put the 3.x javadocs back
> on the site using "api-3_..." i'm just fixing up a few places to link to
> them where appropate.
>
> but anyone who has old bookmarked links to "/solr/api/..." should have
> those links go somwhere as long as the classes still exist (also already
> fixed)
>
>
> -Hoss
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [EMAIL PROTECTED]
> For additional commands, e-mail: [EMAIL PROTECTED]
>
>

I would make a perm redirect (301) from api -> api3.

Api3 -> api 3.6.0 would be a 302 redirect, as it is official.

 

By this browsers will update their bookmarks and google bot will forget about the dying api, too.

 

-----

Uwe Schindler

H.-H.-Meier-Allee 63, D-28213 Bremen

 <http://www.thetaphi.de/> http://www.thetaphi.de

eMail: [EMAIL PROTECTED]

 

From: Robert Muir [mailto:[EMAIL PROTECTED]]
Sent: Wednesday, July 04, 2012 12:23 AM
To: [EMAIL PROTECTED]
Subject: Re: Solr 3.6.0 javadocs are missing from the site

 

that's not what I mean. api/ should die. but I'm ok with api-3 that points to 3.6.0 and so on as the links should never disappear within a major release (except heavy breaks)

On Jul 3, 2012 6:19 PM, "Chris Hostetter" <[EMAIL PROTECTED]> wrote:
: these unversioned links should die, die, die. but can we compromise here?
: instead can we have api-3 and api-4, etc. we realize some external links
: could still break, but given our back compat policy it should be rare...

that's exactly what i'm saying .. sarowe alredy put the 3.x javadocs back
on the site using "api-3_..." i'm just fixing up a few places to link to
them where appropate.

but anyone who has old bookmarked links to "/solr/api/..." should have
those links go somwhere as long as the classes still exist (also already
fixed)
-Hoss

---------------------------------------------------------------------

: that's not what I mean. api/ should die. but I'm ok with api-3 that points

Well then you and i have radically differnet opinions about SEO and good
long term URL practices.

it's one thing to say that a URL like "/java/2_9_0/.../Foo.html" should be
allowed to start 404ing once the 2.9.0 release is considered "too old" and
the docs are taken off the site.

but "/solr/api/.../Foo.html" is very differnet -- since Solr 1.1 it has
always pointed to the *current* javadocs for that class, and is heavily
linked to from the wiki, blogs, bookmarks, and search engines.  The fact
that we now provide copies of multiple versions of the javadocs is no
reason to kill off a bunch of useful and valid URLs that have a lot of
PageRank value and link juice.

If individual class files are removed then sure: those individual pages
will, and should, start 404ing because the specific class being refrenced
no longer exist, but on the whole there is no reason not to continue to
the basic path redirect -- It takes about 60 seconds of effort to toggle
~6 bytes of the .htaccess file to keep those URLs pointed at the "current"
release.  As long as someone like me is willing to do the work when new
releases come out, there is no reason for all those links to "die"

-Hoss

---------------------------------------------------------------------

On Wed, Jul 4, 2012 at 1:28 PM, Chris Hostetter
<[EMAIL PROTECTED]> wrote:
>
> : that's not what I mean. api/ should die. but I'm ok with api-3 that points
>
> Well then you and i have radically differnet opinions about SEO and good
> long term URL practices.

clearly we do: i care about documentation not having broken links.

but linking to api/ is fucked up. Those links *will break* when the api changes.
--
lucidimagination.com

---------------------------------------------------------------------

: > Well then you and i have radically differnet opinions about SEO and good
: > long term URL practices.
:
: clearly we do: i care about documentation not having broken links.
:
: but linking to api/ is fucked up. Those links *will break* when the api changes.

Some of the existing URLs will start 404ing if/when classes/methods are
gradually removed, that is true -- but if you delete the redirect then
*ALL* of the URLs will start 404 immediately, even though we do in fact
have a place we could easily redirect them.  Thats just plain
irresponsible.

If your concern is purely that we should stop linking to "unversioned"
urls like /solr/api/.../Foo.html then fine -- for the most part that will
happen as a natural course of events anyway since the redirect will start
always sending people a specific version URL anyway.  If you want to
proactively go through all the wiki docs and switch all "/api/..." links
to "/api-4_0_0-ALPHA/..." you're certianly free to do that.  (Are you
going to volunteer to manualy keep updating them every release?)

My primary concern is that as long as there are "current" javadocs
somewhere, then /solr/api/.* should redirect to them so that existing
linkages don't break.  it's trivial to keep up to date, and it doesn't
hurt anything.  

If I die, and no one else thinks editing those 6 bytes is worth the
effort to keep them working, knock yourself out nad delete them

:
:
: --
: lucidimagination.com
:
: ---------------------------------------------------------------------
: To unsubscribe, e-mail: [EMAIL PROTECTED]
: For additional commands, e-mail: [EMAIL PROTECTED]
:
:

-Hoss

---------------------------------------------------------------------

On Wed, Jul 4, 2012 at 1:52 PM, Chris Hostetter
<[EMAIL PROTECTED]> wrote:
>
> : > Well then you and i have radically differnet opinions about SEO and good
> : > long term URL practices.
> :
> : clearly we do: i care about documentation not having broken links.
> :
> : but linking to api/ is fucked up. Those links *will break* when the api changes.
>
> Some of the existing URLs will start 404ing if/when classes/methods are
> gradually removed, that is true -- but if you delete the redirect then
> *ALL* of the URLs will start 404 immediately, even though we do in fact
> have a place we could easily redirect them.  Thats just plain
> irresponsible.
>
> If your concern is purely that we should stop linking to "unversioned"
> urls like /solr/api/.../Foo.html then fine -- for the most part that will
> happen as a natural course of events anyway since the redirect will start
> always sending people a specific version URL anyway.  If you want to
> proactively go through all the wiki docs and switch all "/api/..." links
> to "/api-4_0_0-ALPHA/..." you're certianly free to do that.  (Are you
> going to volunteer to manualy keep updating them every release?)
>
> My primary concern is that as long as there are "current" javadocs
> somewhere, then /solr/api/.* should redirect to them so that existing
> linkages don't break.  it's trivial to keep up to date, and it doesn't
> hurt anything.

i dont think we should have a 'current' javadocs link anywhere.

again, lucene doesnt have this.

instead, i already suggested api-4, api-3, etc. This way 'outside'
links can link to a specific major version without much fear, because
its highly unlikely things will break within a minor release.

but some 'api' link as if the damn thing never changes is just insanity.

--
lucidimagination.com

---------------------------------------------------------------------

I just repeat myself:

I would make a perm redirect (301) from api/ -> api3/.
api3/ -> api-3.6.0 would be a 302 redirect, as it is official.

By this browsers will update their bookmarks and google bot will forget about the dying api/, too (with 301 redirect). Api3 is then official link to the actual api of version 3, api4 of version 4, pointing to current alpha (via 302 redirect).

-----
Uwe Schindler
H.-H.-Meier-Allee 63, D-28213 Bremen
http://www.thetaphi.de
eMail: [EMAIL PROTECTED]
> -----Original Message-----
> From: Robert Muir [mailto:[EMAIL PROTECTED]]
> Sent: Wednesday, July 04, 2012 7:35 PM
> To: [EMAIL PROTECTED]
> Subject: Re: Solr 3.6.0 javadocs are missing from the site
>
> On Wed, Jul 4, 2012 at 1:28 PM, Chris Hostetter <[EMAIL PROTECTED]>
> wrote:
> >
> > : that's not what I mean. api/ should die. but I'm ok with api-3 that
> > points
> >
> > Well then you and i have radically differnet opinions about SEO and
> > good long term URL practices.
>
> clearly we do: i care about documentation not having broken links.
>
> but linking to api/ is fucked up. Those links *will break* when the api changes.
>
>
> --
> lucidimagination.com
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [EMAIL PROTECTED] For additional
> commands, e-mail: [EMAIL PROTECTED]
---------------------------------------------------------------------

+1 to what UweSays

On Wed, Jul 4, 2012 at 2:00 PM, Uwe Schindler <[EMAIL PROTECTED]> wrote:
> I just repeat myself:
>
> I would make a perm redirect (301) from api/ -> api3/.
> api3/ -> api-3.6.0 would be a 302 redirect, as it is official.
>
> By this browsers will update their bookmarks and google bot will forget about the dying api/, too (with 301 redirect). Api3 is then official link to the actual api of version 3, api4 of version 4, pointing to current alpha (via 302 redirect).
>
> -----
> Uwe Schindler
> H.-H.-Meier-Allee 63, D-28213 Bremen
> http://www.thetaphi.de
> eMail: [EMAIL PROTECTED]
>
>
>> -----Original Message-----
>> From: Robert Muir [mailto:[EMAIL PROTECTED]]
>> Sent: Wednesday, July 04, 2012 7:35 PM
>> To: [EMAIL PROTECTED]
>> Subject: Re: Solr 3.6.0 javadocs are missing from the site
>>
>> On Wed, Jul 4, 2012 at 1:28 PM, Chris Hostetter <[EMAIL PROTECTED]>
>> wrote:
>> >
>> > : that's not what I mean. api/ should die. but I'm ok with api-3 that
>> > points
>> >
>> > Well then you and i have radically differnet opinions about SEO and
>> > good long term URL practices.
>>
>> clearly we do: i care about documentation not having broken links.
>>
>> but linking to api/ is fucked up. Those links *will break* when the api changes.
>>
>>
>> --
>> lucidimagination.com
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: [EMAIL PROTECTED] For additional
>> commands, e-mail: [EMAIL PROTECTED]
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [EMAIL PROTECTED]
> For additional commands, e-mail: [EMAIL PROTECTED]
>

--
lucidimagination.com

---------------------------------------------------------------------

: > My primary concern is that as long as there are "current" javadocs
: > somewhere, then /solr/api/.* should redirect to them so that existing
: > linkages don't break.  it's trivial to keep up to date, and it doesn't
: > hurt anything.
:
: i dont think we should have a 'current' javadocs link anywhere.

Now we're just repeating ourselves.  here i'll paste my comment again...

> If your concern is purely that we should stop linking to "unversioned"
> urls like /solr/api/.../Foo.html then fine -- for the most part that will
> happen as a natural course of events anyway since the redirect will start
> always sending people a specific version URL anyway.  If you want to
> proactively go through all the wiki docs and switch all "/api/..." links
> to "/api-4_0_0-ALPHA/..." you're certianly free to do that.  (Are you
> going to volunteer to manualy keep updating them every release?)

...if you don't think that we, as a project, should linke to something
like "/solr/api/..." fine - i own't argue that.

i'm saying that we should leave the redirect in place so existing
docs/bookmarks/webpages/search engines won't get 404s

that's all i'm saying.

you want to add other major version redirects, or update wiki links, or
anything else, knock yourself out.

i'm perfectly happy with the /solr/api-3_6_0/ and /solr/api-4_.../ links
moving forward, i just don't wnat ot break existing URLs for people.
-Hoss

---------------------------------------------------------------------

: I would make a perm redirect (301) from api/ -> api3/.
: api3/ -> api-3.6.0 would be a 302 redirect, as it is official.

That assumes that anyone who linked or bookmarked "/api" specificly
expected the 3.x links.

/solr/api/... has existed since solr 1.1 and has always been updated to be
the "current" docs when a new release comes out.  

hence my point about keeping the redirect up to date pointing at the
current version, so the URLs continue to mean what they have always ment
to anyone who has linked to them or bookmarked to them -- we can't assume
they only wanted "Solr 3.x" javadocs just becuase that's wha they were
most recently -- some people may have linked to them when they were 1.4 or
1.1 javadocs.

This isn't rocket science -- it's basic SEO.

wether it's a 301 or a 302 is a philosophical debate.  Personally i think
302 makes the most sense according to the spec and browser/search engine
behavior -- but i don't give enough of a fuck to argue about it, but the
redirect needs to exist in some form.

-Hoss

---------------------------------------------------------------------

On Wed, Jul 4, 2012 at 2:12 PM, Chris Hostetter
<[EMAIL PROTECTED]> wrote:
>
> : I would make a perm redirect (301) from api/ -> api3/.
> : api3/ -> api-3.6.0 would be a 302 redirect, as it is official.
>
> That assumes that anyone who linked or bookmarked "/api" specificly
> expected the 3.x links.

thats the whole problem with /api: its not defined at all.

having shit like this just turns into 'lets blame the release manager
when things change and its not the way i want'.

Lets either kill it or make it a 301 and discourage its use in the future.

same goes for download redirect links (I will open an issue tomorrow:
either we remove these download redirect llinks completely, or we fix
them to take versions, because having to add ?'s with bogus stuff on
the end to prevent caching etc is really annoying, and having to
delete old news because old releases now link to new releases is
crazy).

--
lucidimagination.com

---------------------------------------------------------------------

On Wed, Jul 4, 2012 at 2:25 PM, Robert Muir <[EMAIL PROTECTED]> wrote:
> same goes for download redirect links (I will open an issue tomorrow:
> either we remove these download redirect llinks completely, or we fix
> them to take versions

I don't know the details behind the download redirect links except for
the fact that they were added so we can track downloads.
So just in case I miss the issue... whatever we do, we should not lose
the download tracking.

-Yonik
http://lucidimagination.com

---------------------------------------------------------------------

On Wed, Jul 4, 2012 at 2:47 PM, Yonik Seeley <[EMAIL PROTECTED]> wrote:
> On Wed, Jul 4, 2012 at 2:25 PM, Robert Muir <[EMAIL PROTECTED]> wrote:
>> same goes for download redirect links (I will open an issue tomorrow:
>> either we remove these download redirect llinks completely, or we fix
>> them to take versions
>
> I don't know the details behind the download redirect links except for
> the fact that they were added so we can track downloads.
> So just in case I miss the issue... whatever we do, we should not lose
> the download tracking.
>

downloads working > downloads tracking
--
lucidimagination.com

---------------------------------------------------------------------

: thats the whole problem with /api: its not defined at all.

it has bee nvery clearly defined since it was created: "the latest
javadocs" ... just because we no longer explicitly link to it, doesn't
mean we should stop trying to live up to the point of the link --
especially not when it's so fucking easy to do.

: having shit like this just turns into 'lets blame the release manager
: when things change and its not the way i want'.

where do you get that anyone is going to blame release managers for
something?  having this redirect isn't going to break anything, nor does
it have anything to do with anything an RM should give a fuck about.

the only reason we had a hicup with it on tuesday was because that was the
day we made the change from only hosting single copy of the solr javadocs,
re-using a single path for each new version, to having multiple versions
with distinct pathes -- and when we made that change we did *NOT* have any
redirect like this in place at all.

that change could have been made at any time, regardless of wether it
involved a new release, regardless of wether it was done by an RM, and the
problem would have been the same: the missing redirect ment old links
broke.

that was a one time change, that will never affect any other release in
the future ever again: we just keep adding new directories for the new
docs.

having this redirect doesn't affect that in any way shape or form

: same goes for download redirect links (I will open an issue tomorrow:
: either we remove these download redirect llinks completely, or we fix
: them to take versions, because having to add ?'s with bogus stuff on

I already opened an issue for that when we noticed this during 3.6 .. no
one who cares about the google analytics and understands javascript has
bothered to pick it up...

https://issues.apache.org/jira/browse/LUCENE-3978
-Hoss

---------------------------------------------------------------------