Too much here to reply to all the points at once... but I'll take a stab at some of them.
- "maven" directory in the binary release - that was a mistake/bug - has been fixed in build.xml - I'm definitely for separate source and binary releases - makes so much more sense post merge. solr's "src" is particularly great now... one can modify any part (lucene, modules, etc) and easily rebuild. "bin" really makes sense given the size of "src" (size, number of files, more complex directory structure, etc), and the number of solr users that want to know nothing about java. - in the future, I think it makes sense to cut down the binary distro even further... cut out the complexity of including the site, cut out the javadoc. - no, there is no requirement that binary artifacts contain source code -Yonik http://lucidimagination.com On Thu, Mar 10, 2011 at 6:49 PM, Chris Hostetter <hossman_luc...@fucit.org> wrote: > > : Artifacts are located here: http://s.apache.org/solrcene31rc0 > > Finally got a chance to look at 3.1 rc0. > > my comments are below -- they are in the order i encountered them ... > stream of conciousness. Note that this was my first real chance to look > at the new packaging work folks have been doing to deal with the merged > dev tree (ie: the solr source only packaging, and how we include the > lucene jars in solr releases, etc...). I also have to confess being > woefully behind on reading hte dev list and jira, so forgive me if any of > this has already been discussed / dealt with... > > The short summary, i'm a -1 for these RC0 packages.... > > I focused on the *.tgz files, assuming (for now) that the zip files are > consistent.... > > #### > I started with apache-solr-3.1.0-src.tgz > > The first thing that jumped out at me when i unpacked it was that the > directory structure i get was definitley not what i was expecting. As a > committer familiar with how the tree works, i understand what these > directories are, but i suspect this may confuse folks who have downloaded > solr in the past, and those that haven't are going to be double confused. > > At a minimum the fact that there is no top level README.txt file seems > like a major oversight that we should definitely deal with. > > It also seems like we should probably have a README.txt file in dev-tools > (may not be needed if a top level README.txt explains it, but it still > seems like a good idea) > > looking in the "solr" directory, i look at it's README.txt file, and see > the section "Files Included In Apache Solr Distributions" it refers to a > lot of stuff that is not actaully included in the distribution (because > this is the *src* only distribution). it's one thing to assume people > downloading the *src* package will understand why the war nad jar aren't > in solr/dist/ but we also refer to a "docs" directory that doesn't exist > until they build it. > > If we really want to ship a Solr src only package (which i think it's a > great idea) we need to figure out a way to rework/structure this > README.txt file to make sense for both cases (or ship two differnet ones > -- but that seems like a bad idea) ... we could start by moving the > "Instructions for Building Apache Solr from Source" up and rewording the > "Files Included" section ... but even before that i notice we refer to > docs/tutorial.html in the "Getting Started" section > > looking only at the src release, i couldn't even find any documentation on > how to build the tutorial and other files -- again: since this is a src > only release, it may be ok to only include the "src" of the tutorial, but > we should at least mention somewhere how to build it. > > After running "ant test" from the top level, and "ant example" in the solr > dir, i had a working example dir that seemed to be functioning fine, but i > still had no javadocs for solr. when i tried to run "ant javadoc-all" in > the solr directory, javadoc actaully failed with a DocletAbortException > stack trace because of a FileNotFoundException when trying to copy > ./build/docs/api/prettify/stylesheet+prettify.css (i have a > ./build/docs/api/prettify/ but it's empty ... not sure what target was > expected to populate it) > > switching tracks, i looked at solr's CHANGES.txt I noticed a few small > things... > > * under the "Versions of Major Components" we list "Apache Lucene trunk" > * below the 3.1 changes is a list of 1.4.0 changes -- but no 1.4.1 > changes? > * we had discussed on the dev list that we should stop including changes > from older "major" versions (ie: 3.x CHANGES.txt would only list things > from 3.0 on) ... i thought i remembered people agreeing that was agood > idea, but maybe i was imaginging that. > > > As i mentioned -- most of the issues were really about documentation and > expectation setting for a "src" release. the README and ant task > descriptions we have were never really written with that idea in mind. > > #### > Next I looked at apache-solr-3.1.0.tgz > > Other then the minor CHANGES.txt stuff mentioned above, this package made > much more sense when i first unpacked it. There is a top level > README.txt, and most things mentioned in the README.txt file seemed to > exist -- dist and docs. Looking at the tutorial, i noticed the first > glitch: it lists the Solr version as "3.0.0.2011.03.06.20.12.33" (which i > know means it wasn't regenerated with the forrest properties set by ant). > > Other then that, the tutorial looks good, the example seems to work, and > the link from the tutorial to the javadocs works and i can browse them > just fine. > > Then I realized there was no "src" directory. i'm not sure if this was > intentional (don't all of our releases need to include the source, even > the binary ones?) but at the very least we have a problem with the > README.txt which says the src should be there and that you should be able > to rebuild it with and (except that we also don't have a build.xml file > even if we had the source) > > This binary distribution also seems to be more redundent then it needs to > be with the jars, everything in dist/ seems to be duplicated in dist/maven > -- again, maybe this was intentional, but if so why? ... if i wanted the > maven jars, wouldn't have just downloaded them from maven instead of > downloading the binary release? is there a value add to including them in > both directory structures? > > (at this point i also discovered that there are "sources" jars in the > maven directory, so we are in fact including the source i nthe binary > releasees -- but if this is intentionally how we want to include them (and > the maven jars aren't a mistake) then we should note that in the > README.txt > > The number of "lucene" jars included in the release is also odd -- they > are embedded in the solr.war obviously, but not included anywhere else. > so people wanting to do something like use apache-solr-core-3.1.0.jar to > embed solr in their app still need to get the lucene jars from a distinct > release ... except that there does seem to be 3 lucene jars included in > ./contrib/analysis-extras/lucene-libs (i suspect this was a mistake in an > intentional exclusion of those jars) > > ### > Moving on to lucene-3.1.0-src.tar.gz > > Similar README.txt problem as solr ... jars, wars, and javadocs are > mentioned that don't exist in the src release, and there is not verbage > mentioning that these files won't exist until you build them. > > Similar question about CHANGES.txt still listing changes in old releases > ... thought we wnated to prune those down. > > > In general, i'm wondering if there is really any value anymore in having > distinct src artifacts for "lucene-java" and solr ... my gut inclination > is that while it certainly makes sense to have distinct binary releases > (people using just the core library really don't care about hte baggage of > a fully solr release) for the source releases, we should just have a > single package containing a full checkout of hte top level build dir, so > people get all the source (and all the top level dev-tools) ... assuming > we have a top level README.txt that is about building *all* of the source, > then that would also help deal with some of hte other issues about the > individual solr/README.txt and lucene/README.txt files refering ot things > that aren't there until you build them. ... but agian, i assume there > was some discussion about this that i missed, and there is agood reason > for maintaining distinct src packages. > > ### > Lastly: lucene-3.1.0.tar.gz > > Similar to my question about the solr binary release: aren't we required > to include source in all binary releases? in this case there aren't even > any maven jars in this packaging (which makes me doublely question the > maven jars in the solr package) which means we don't even have the source > in jar form. > > if exclusion of the src is intentional here, then we should probably > exclude the BUILD.txt file as well. > > one other thing that jumps out at me is that the README.txt refers to > contrib/demo/luceneweb.war but even in this release that doesn't exist, > just contrib/demo/lucene-demo-3.1.0.jar (and looking back at the source > release i think that's just blatently out of date -- it looks like the war > form of hte demo was completley removed from the build.xml) > > this got me looking at docs/demo.html to see if it still refers to the > demo war (it doesn't) where i notice the "Setting your CLASSPATH" > instructions suggest that lucene-demo-{version}.jar will be found in the > main direcotry along with lucene-core-{version}.jar ... we should update > that to be contrib/demo/lucene-demo-{version}.jar > > other then that -- things look good. jars all seem to be there, manifests > look good, and the demo runs correctly > > #### > What next from here? > > I'd like to try and help fix some of this, but except for some of hte > really trivial stuff (version numbers in solr CHANGES.txt and tutorial; > demo war refs in lucene README) i'm not really sure how to proceed -- > it really depends on the overall strategy of the "src" only packages (was > there a thread or jira on this? ... i really can't find any discussion > about it) to decide what to do about the README.txt files and other > documentation. > > > > -Hoss > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org > For additional commands, e-mail: dev-h...@lucene.apache.org > > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org For additional commands, e-mail: dev-h...@lucene.apache.org
