First off, I get that this issue really seems to be subject to personal preference, so I think there is no much point in convincing someone who prefers it the other way around. I'm still gonna try it

How is that distracting?

To me, a library has two major parts, public-facing parts (API/SPI) and non-public parts (internal). I find it just much easier to handle (as a developer of that library but also as a consumer) if this split is done at one place, i.e. at the top of the hierarchy. Once I'm in either sub-tree, I don't have to deal with the other half any-more.

When the split is done on the leaf-level, I as a user stumble upon internal packages again and again, e.g. when navigating through the package tree of the library, but also when working with auto-completion. In the top-split model, once I've tabbed to org.hibernate.search.foobar, my IDE will never suggest any impl type again. In the leaf-split model, it will suggest impl types for each new sub-package I'm tabbing into.

Sorry I don't mean it with sarcasm I'm genuinely not getting it, especially not why this is so important vs. keeping an existing API as is.

But my suggestion is exactly to leave the "API" as is (comprising API and SPI packages) and only move the impl packages to a separate sub-tree, moving it out of sight for a consumer of the library. I don't see why leaving the impl packages at the leaf level makes the library better consumable for users, IMO the opposite is the case.

Btw. I really appreciate your non-sarcasm, this greatly helps with keeping the discussion productive. Regarding importance, it's surely not super-important, but personally I just feel that the top-split model makes a library better consumable.

This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira