Fully publish and support PioneerAnnotationUtils

[eeverman]

A thought: This project's support classes are just as valuable (maybe more so?) than its current set of extensions.

I'm creating custom JUnit extensions for a separate project: AndHow (a configuration utility).
JUnit's AnnotationSupport methods don't quite work for extensions trying to find their declaring annotation for configuration (i.e. when the annotation has parameters) - I'm guessing that's why this project wrote its own PioneerAnnotationUtils class.

Presumably, the PioneerAnnotationUtils solves the problems of locating annotations from extensions following JUnit's semantics, which would be hugely useful for anyone else creating extensions. Unfortunately, the PioneerAnnotationUtils class warns:

DO NOT USE THIS CLASS - IT MAY CHANGE SIGNIFICANTLY IN ANY MINOR UPDATE.

I propose that all the support features used by JUnit Pioneer be split out into a separate artifact, perhaps junit-pioneer-support, and that support methods be marked with support levels similar to what JUnit does for its support methods, e.g. MAINTAINED, EXPERIMENTAL, etc.. That library might become the basis for many other custom built extensions. I think this is also in keeping with the description of the project:

It aims to spin off successful and cohesive portions into sibling projects or back into the JUnit 5 code base.

It's hard to spin off extensions if each one has to re-implement all the support pieces that this project has built up :-)

[Michael1993]

Hi @eeverman ! Thank you for the suggestion. We will discuss and get back to you.

JUnit's AnnotationSupport is a very robust tool, so I'm kind of wondering what you are trying to do to find it lacking. Could you tell us a bit more about your project?

We had an issue open a while ago about marking our API with API Guardian like you suggested.
The decision was that we don't want to do that.

[eeverman]

My project, AndHow, is a project configuration util. It lets you declare strongly type configuration parameters anywhere in your code like this:
static final StrProp DATABASE_URL = StrProp.builder().startsWith("jdbc:").build();
...and then finds and validates the configured values for them from any source (env vars, jndi, sys props, etc.) at startup.

The JUnit extensions I am working on are specifically for AndHow: The intention is to let the user specify a properties file to be used for a test like this:

@Test
@UseThisPropertiesFileForAndHow("MyFile.properties")
public void someTest() { }

So, bottom line, unless you are using AndHow, you wouldn't need these extensions.

[nipafx]

It's great to learn that PioneerAnnotationUtils provides value beyond its internal use. 😃 I hesitate to spin it into its own project, though. That class has quite a tumultuous history and we have ideas that may lead to further, deep changes in the future. I'd rather not lock us into a compatibility commitment.

Of course we could just mark it as experimental, but if what you're say is correct, that it "might become the basis for many other custom built extensions", that wouldn't help because then different extension artifacts may depend on different versions of the new support artifact, which can quickly lead to unresolvable conflicts.

Instead I invite you to just copy-paste the source code. EPL 2.0 is pretty permissive, so there's a good chance that it's compatible with your project's license. If it is, just copy the code you need into your utils. 👍🏾 Please change the package name, though, to avoid split packages.

[eeverman]

Thank you, @nipafx, for the info. I would like to do this: include some of the source code of PioneerAnnotationUtils in AndHow, which is under the Apache 2.0 license (likely w/ some small modifications).

Reading through the EPL 2.0, it sounds like I may need to dual license that as a result. Does anyone on this project have the expertise to comment on those actual requirements? I'd prefer to not have to complicate the license on my project if I don't have to.

Naturally, the EPL 2.0 FAQs manages to not directly comment on this situation.

[Michael1993]

Does anyone on this project have the expertise to comment on those actual requirements?

I can safely say, no. 😅

[Bukama]

Same for me - not a lawyer 🤷‍♂️

[nipafx]

I can't say anything definitive on the matter either. But... couldn't you create a separate one-file project under EPL and then depend on that from your project? That would effectively be the same as what you asked us to do minus the issues I laid out earlier.

Given the age of this issue and our lacking desire to implement it, I will close it, but please feel free to reply or reopen if you think we can help more. Also, we'd be interested to learn what solution you went with in the end. 😃