Am 21.07.2013 um 15:21 schrieb Marshall Schor <[email protected]>: > Thanks for your quick testing / checking. > > Some answers below. > On 7/20/2013 3:35 PM, Richard Eckart de Castilho wrote: >> Cleared local repo fully. >> >> Checked out tag and built: ok. >> >> Installed Eclipse plugins in dropins folder and checked if usual editors >> etc. are present: ok. >> >> Opened description in Component description editor: ok. >> >> Upgraded uimaFIT to uimaj 2.4.1 artifacts and built: ok. >> >>> [X] +1 OK to release >> >> Some remarks though: >> >> uimaj-2.4.1-bin.zip - README - Document title not properly aligned with >> horizontal line below > > hmmm, looking at this in an plain text editor (monospaced fonts), everything > seems to line up. Can you say more about what's wrong?
There are 3 tab chars and 0 space chars before "Apache" There are 2 tab chars and 2 space chars before "----…" >> uimaj-2.4.1-bin.zip - resource should never be outside packages / at root of >> JAR: >> uima-core.jar - "resourceSpecifierSchema.xsd" and "uima.ecore" >> uima-tools.jar - JCasGenFileConsoleLogger.properties > Why do you assert this; can you say more? These have been at those locations > since the early days. I suspect that user code would (by now) have > dependencies > on this positioning, and moving these would be disruptive. > > The normal reason to put things into packages is to avoid name conflicts where > that's somewhat likely (due to (usually) hundreds of names being generated by > different developers over time). The down-side is that the "names" get longer > (as they are prefixed by package names). If resources are at the root of the classpath, there is a higher chance of collision. Cf. [1,2]. In my opinion, the best practices that apply to classes apply to resources as well, after all, class files are little more than very common resources ;) Generally, this is a special instance of "two artifacts of different names better not contain the same package" and "thou shalst use merely package names thou ownest" best practice. That one recently bugged me in another context where some-parser-models.jar had a /models/parser.ser and some-nlp-framework-models.jar also had a /models/parser.ser. Nasty… Placing resources at the root of the classpath creates a stronger requirement than the usual "thou shalst not have different versions of yonder JAR on thy classpath". Some frameworks expect data at certain well-known locations, e.g /plugin.xml or /META-INF, but clients in these frameworks should be able to handle this case by using ClassLoader.getResources() instead of Class(Loader).getResource() or by handling the complete JAR file access themselves. [1] http://docs.oracle.com/javase/specs/jls/se7/html/jls-7.html#jls-7 [2] http://docs.oracle.com/javase/specs/jls/se7/html/jls-7.html#jls-7.4.2 >> uimaj-2.4.1-bin.zip - library names in lib folder inconsistent: >> uima-core.jar >> uima-cpe-jar >> … >> but: uimaj-bootstrap.jar >> Shouldn't these all be uimaj-*? > I agree they're inconsistent. The names are the way they are for I think > purely > historical reasons. There was debate (much) earlier on the mailing lists > about > names, mainly around following more normal Maven naming conventions, where the > name of the Jar includes the version information. It was thought (back then) > that changing the names would annoy users who were upgrading, and who would > (potentially) need to change scripts when installing a new version. So, we've > left these alone to enhance user stability. > > The "j" suffix on uima arose when it was realized that there were a variety of > uima implementations for different language embeddings - j for java, cpp for > C++, being the main 2. Ah, yes… the version for the Java flavors of UIMA are 2.4.1-SDK, but should probably be renamed as well… e.g. 2.4.1-J to go along with 2.4.0-C (shouldn't that be CPP or C++?). >> uimaj-2.4.1-bin.zip - Why are the docs not in the "docs" folder, but in >> "docs/d"? > This was done along time ago as part of the docbook design which, if the docs > are in a particular folder structure, can be used to generate proper > cross-docbook links in PDF documents as well as html docs, both on the > website, > and when people download these to local disk. This was also intended to > faclitate sharing and standardization of common boilerplate. See: > http://uima.apache.org/dev-docbook.html ; the /d/ directory was intended to be > the shared "docbook bookshelf" that made this possible. > > Finally, at one point, we had an arrangement with "infra" where we could avoid > putting into SVN large generated documentation (think of the big sets of > javadocs, as well as our html / pdf "books"), and yet have these available on > our website. This arrangement was an rsync from people.a.o in our website > docs/d directory, to the real website in the same directory. > > This arrangement was teminated by infra when they decided to have everyone use > SVN pubsub or their CMS system for websites. So shall I open an issue for the next release to get rid of the spurious "d" folder? -- Richard
