[Junit-devel] Structure of junit.contrib

[David S. <da...@sa...>]

All,

As you may have heard, I'm planning to start a junit.contrib project.
In this mail, I'll first review the reasons for such a project, and
secondly, I have a proposal for its structure, and I'd like feedback.

=== BACKGROUND: REASONS FOR junit.contrib ===

JUnit has always officially strived to be "the intersection of all
useful Java testing frameworks".  Thus, the goals for code that gets
into the junit repository include that it should:

1) Minimize dependencies on external libraries or particular JDK
versions beyond a widely-used minimum.
2) Be very unlikely to change API moving forward.
3) Emphasize opportunities for extension over the richness of core features.
4) Have potential usefulness to all Java developers, regardless of
their application domain.
5) Match in style to the current JUnit codebase.

Many people have made JUnit extensions that would be useful to a
healthy portion of Java developers, but do not meet all of the above
criteria.  For example, the extension may target a particular IDE, or
data that is stored in a SQL database, or in XML, or it may be
experimental, and likely to change API, or it may require an external
dependency.  Also, as the popularity of non-Java languages on the JVM
has grown, some people have made extensions to JUnit that make it
easier to use JUnit's core functionality in ways idiomatic to those
other languages.

It has always been an option for developers of these extensions to
publish them on their own repositories.  However, having a central
clearing-house as an option for extension developers has some
advantages, including discoverability, documentation, and dependency
management.

The goal is for junit.contrib (just started on
https://github.com/dsaff/junit.contrib) to be this clearing house.
All Java classes in this project should be in packages prefixed with
org.junit.contrib.

Now, the

=== PROPOSAL ===

The root structure of the project will contain:

/
  README
  docs/
  java/
  scala/ [?]
  clojure/ [?]

Thus, a folder for overall documentation, and then a folder
per-language.  I haven't thought about how non-java language
extensions should be organized.

Under java, there should be a folder per "subproject" (names chosen,
with apologies, by http://en.wikipedia.org/wiki/Special:Random):

java/
  brewmasters/
  callisto/
  hekler/
  norway/
  ...

Each subproject should be organized as its own maven project:

java/brewmasters/
  pom.xml
  src/main/java/org/junit/contrib/brewmasters/...
  src/test/java/org/junit/contrib/brewmasters/...

As potential users and contributors to such a repository, are there
pitfalls in this organization that I should be aware of in advance?
Thanks,

   David Saff