A little late to the party, but

your top level approach makes it clean when you traverse the tree in your file system but it's not how you consume an API.

How do you consume an API then? A package structure is there bring structure to your source code. Ideally it tells you already a lot about the code by jsut browsing this package structure. So who are our "users". In the case of API consumptions it is other developers. If I have a hard time browsing the provided packages, why would it be better for them. I get regularly confused with all these different levels of spi and impl and I am working with this on a regular basis. Also as a user/consumer I would appreciate the possibility to for example browse into org.hibernate.search.spi and get and overview of all spi contracts available. I don't see what you mean with "it's not how you consume an API".

In other words it feels cleaner for the API writer but not necessarily for the API consumer where the impl.

So you are already admitting that it is cleaner for the API writer. That's because we are developers and think in certain terms. Given that the API consumers are also developers, I'll argue that we should fulfill their expectations.

Comparing Search to Validator (where we did the split at the top level) I must say the latter makes just more sense, in particular from a development point of view. And in the end that is imo more important than some intangible user benefit. If the package structure hinders/confuses us during development, something is wrong.

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