archunit-example should have (completely) self-contained build

[gernotstarke]

When running 'gradle test' on the archunit-example directory, I get:

53 tests, 0 failures, 53 ignored.

As an ArchUnit-user, I don't want to test the whole library, but only a (small) example...

(this issue belongs to the more general #22 )

[codecholeric]

But those 53 tests are tests only for archunit-example, these are 53 tests, testing the main code of archunit-example and @ignored, since they all fail to demonstrate, how errors would look like...
They are also reused within archunit-integration-test, where the expected errors of those "usecases" are asserted.
You're certainly right, that there should be a README.md explaining this...

[codecholeric]

By self-contained you mean, it's a completely separate project, where you add the Maven coordinates of archunit as a dependency?
Because in my view that would have some drawbacks, too.

• At the moment, all example rules are at the same time used for integration tests, since integration tests should run against the current code base, I'd have to duplicate the rules then, which I don't like too much
• It would be easier to forget to adjust archunit-example, if it would refer to a possibly different version (it would only be up to date, if the maven install step was performed, or the current version is published as SNAPSHOT
• Of course I could make archunit-example:compile running after archunit:mavenInstall, thus enforcing mavenInstall, when archunit-integration-test:test is run, but this doesn't feel like good practice as well

On the other hand, the only advantage would be to not have to compile the base archunit as a user, who just wants to run archunit-example (which on my current machine takes 3s altogether).

[gernotstarke]

as a potential new user, I don't care about these drawbacks - I need examples to get started.

And: The example should be KISS (meaning: shortest possible setup time, just a single gradle build task ("run")).

[codecholeric]

Okay, but at the moment, the process is

git clone $ARCHUNIT_URL checkout
cd checkout/archunit-example
../gradlew build -P example

I wouldn't exactly call that a complicated setup 😉 (I would imagine most people would import the project into their IDE anyway, and run selected tests?)

It would also be possible, to only run reasonable tasks, if -P example is set, so that ./gradlew can be run from the root without the whole project being built and tested.

I'm just trying to figure out, if there is no solution, that is convenient for an user of archunit-example and a developer / CI running the full build.

[gernotstarke]

Peter, you're right, it's not really complicated. But as a user, I don't want the source + tests, just the example...

You might move the examples to a distinct github repository and include them into the main ArchUnit via git. Then the examples might get their own build (+ doc), AND your goal of DRY is supported.

The CI needs to pull changes from archunit-examples before performing the rest of the build,
but that should be done by:

git submodule update --remote
git add .
git commit -m "updated submodule"
git push

does that sound reasonable?

[codecholeric]

The submodules way has just the problem, that either it's not self contained (if I would throw the current archunit-example into a submodule, the build.gradle would still depend on the whole build), or I have to depend on the released version, which doesn't make sense for integration tests during development.
I was pondering, it's probably, because I've mixed some use cases here, on the one hand the examples for new users, on the other hand the examples during development, that also serve as integration test cases.
Maybe it would be a good idea to separate these use cases?
For example, I could maintain a second example repo, that houses a self contained build of archunit-example (like a user would set it up, i.e. Maven Central dependency, etc.), and I could push just the released versions there (which makes sense anyway, I guess, because for a new user, it would make no sense, to check out the examples of master, that refer to the current state of development, but the examples for the last released version)
That would make it easier for users, and the overhead would be minimal, since I only have to update that repo once per release.
What do you think?

[gernotstarke]

Closed, as the examples have been extracted to a separate Github repository