On 7/21/2013 10:13 AM, Richard Eckart de Castilho wrote: > 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 "----…" ok, thanks, fixed.
> >>> 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]. True, in the abstract, but in this case, I don't think it's an issue, since there's only 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 ;) I agree also that unless there are special circumstances, this is the best practice. > > 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". yes, true. > > 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++?). you're talking about the version names in "Jira", I think, right? There, because there are other 2.4.1 java things - like uima-as, I thought it was clearer to include SDK. These are rarely typed in the Jira interface, I think - they're more of a menu pick - so I thought the extra bit of info was useful. > >>> 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? Looking at the pros / cons: Pros: reduces the complexity slightly, reduces the path by 2 letters, puts all docs together. Cons: is a change which could require user's to modify things (potentially makes work for users), removes the grouping of generated docbook documentation, requires some work to crawl through and / or check the docbook generation, to insure file sharing and inter-book references are working correctly. In balance, I would not change this; mainly because I think there's potential for unnecessary user disruption. -Marshall > > -- Richard > >
