Standardize and make file/directory layout configurable

Scenarios can live both in Maven main or test directories, according to the user preference.

The default is in main as to encourage the separation of modules for code and integration tests. But the "test" scope is also configurable.

The examples (especially the trader one) already present documentation of a typical and suggested Maven usage. We could of course improve and expand on the written documentation.

I agree with Chris, based on my own pain - some English text would help here.

>> But the "test" scope is also configurable.

If by "scope" you mean the test directory, I don't think so.
See JBEHAVE-454.

>> The examples (especially the trader one) already present documentation of a typical and suggested Maven usage.

I strongly disagree with the overall documentation philosophy that "examples are all that's needed". The reader often can't understand "why" in examples - or worse, infers intent where none existed.

In the current case, the examples show the story code being mixed in the same source tree with the production code. I don't get this at all - is the intent to ship the story code as part of the production jar, or "exclude" it, or something else? This is very idiosyncratic. From the lack of an exclude in pom, I'd guess that the intent is to just bloat the production jar. Of course, this all means that unless some dynamic binding is used, the production compile dependencies have to include all the dependencies for the test code.

I'm probably way off the mark here - but that's my point! If the intent isn't stated, I'm left to guess - often badly.

JBehave's philosophy is not that just "examples are all that's needed" - rather examples complement other forms of documentation. But working examples are in our opinion a very informative form of documentation.

If you let us know where you'd like us to expand on the documentation, we'd be happy to. And we always welcome documentation contributions based on the users' experience.

The point of having the stories in the src/main rather than in the src/test is that these are meant to be integration testing modules, which are never released into production. src/test tends to be reserved (in Maven conventions at least) for unit testing. That said, you're welcome to use src/test for integration testing too and there are examples to do that (see comment on JBEHAVE-454). We can add a doc page on this.

Mauro,
If "these are meant to be integration testing modules", why is the production code in the same module with the integration test code? I'm still confused. Do you assume that the user will separate them into different modules when doing real work? If so, I'd suggest doing so in the examples too - or if not, make it clear what the real-work intent is via documentation.
-Ed

Added examples-philosophy page clarifying some of the issues raised (JBEHAVE-457).

The new page looks good - the key sentence, for me, is the last one on the page:

It constitutes a test harness that verifies the "production code" that is found in the JBehave core modules.

FWIW, I suspect that most folks will assume, like I did, that the production code under test was the game, trading system, etc. I could be wrong, though!