Clean up / align internal structure, names, etc.

The current milestone we work on is called “Cleaner Pioneer” and includes issues covering several different like infrastructure, refacotring, polish and more. Goal is to build a solid base for future work (goal is version 1.0). But in my opinion one aspect of the term “Cleaner Pioneer” is missing: The current state of the lib itselfs is a mess in terms of folders, naming. This issue will show some points which in my opinion should be cleaned up / aligned. Maybe there are even more.

Definition of annotations

Current state

Currently most annotations are declared in own interface-files, but not all (e.g. @TempDirectory is definied inside the TempDirectory class). Repeatable annotations (here I mean the “plural” ones that hold the array, e.g. @ReportEntries) are also declared in own interface-files, regardless the fact, that they are never used as an annotation.

Proposal:

We should define a standard so all annotations the same way. Here we should go for defining the declaration inside own interface-files (e.g. @ReportEntry).

A special case may be repeatable annotations: I accidently stumbled over this article about declaration of repeatable annotations. After reading it I think this is a nice way to provide a more intuitive and cleaner API. It also makes it easier to compare that both annotation have the same @Target and @Retention. So I suggest to following the guidance in the articel and put the array holding annotations of repeatable annotations inside the corresponding one.

Location of annotations and other files

Current state

Currently annotations, their extensions and all other files (e.g. ArgumentProviders, InvocationContexts or Utils) are declared inside the org.junitpioneer.jupiter package. A special case are the files or the parameter extensions, which were moved into a subpackage for better overview.

The JUnit API is declared in org.junit.jupiter.api and subpackages of this (e.g. org.junit.jupiter.api.extension). Note: It’s also declared in a own java module but for pioneer we have already decided (see #25) that we don’t want to build a multi module project (at least not yet).

Proposal:

As annotations are the API of pioneer and to get somehow aligned to JUnit I suggest to move:

• all annotations to org.junitpioneer.jupiter.api or sub packages of it, e.g. params for extensions / features with a lot of annotations.
• all extension implementations and their need classes (e.g. ArgumentProviders, InvocationContexts) to org.junitpioneer.jupiter.extension
• all other files (e.g. Util) to stay in org.junitpioneer.jupiter

As for now the vintage package should stay as it is as I don’t see much additional content their. I know that moving around API classes is something critical but as of now pioneer has not reached version 1.0 yet, I think we can make thise movearound if we want to. If we don’t want to do that we can still leave the annotations in org.junitpioneer.jupiter and only move the non-API class Util to another package.

Naming convention

We should think about some naming convetions, like every extension should be suffixed with Extension like ReportEntryExtension. Almost all do this at the moment, except TempDirectory. Maybe we should definie this too for ArgumentProviders, InvocationContexts and something like this.

What we should also consider are names of extension namespaces.

Here I suggest to define that the Namespace class and the extension class name should be used (following exampe is from the DefaultLocaleExtension).

import org.junit.jupiter.api.extension.ExtensionContext.Namespace;

[...]

private static final Namespace NAMESPACE = Namespace.create(DefaultLocaleExtension.class);

This would mean we have to clean up other usages like in the RepeatFailedTestExtension where the namespace definition looks like the following:

private static final Namespace NAMESPACE = Namespace.create("org", "codefx", "RepeatFailedTestExtension");

In the vintage package there’s a mix up

private static final Namespace NAMESPACE = Namespace.create("org", "junit-pioneer", "ExpectedException");

More meaningful tags

Some of our tags are just useless. Best example for this is the enhancement example. Everyhing is an enhancement, regardless if it’s a new feature, a bugfix or a refactoring. @nicolaiparlog mentioned in chat, that he initally used the tags of Junit. I’ve created a list which compares the tags (and tries to match them). In the time since the inital creation of our tags, JUnit has created a bunch of them. We should decide which of them we also want to use. An easy way would be to update my list and then change the tags ascynchronuous so we don’t have to do this on stream

[Bukama]

As no further comments were added about the labels I updated them according to my suggestion (link see above)

[aepfli]

nice tagging me, now i need to read the wall of text you to left behind 😉 - just kidding

definition of annotation

I do not have a strong opinion regarding that, although i believe a project is most easy to adopt and to follow, as long as you follow some defacto standards. As it makes it easier to adopt for others. hence that i will try to find some time and look into other projects, and what is the most common way. i understand that sometimes reducing the cluttering is a good thing, but if it is on cost of maintainability and usual navigation through a project, it might not be ideal.

Github tags

the list looks fine to me - to be honest, i am getting lost in all those tags all the time, and sometimes to many tags is also not a good idea. but so far the list looks good. i think i could label tickets properly. maybe we should define that there is at least a type, status and theme provided for each task. and when we see one, to enhance the issues with appropriate labels (which we obviously should do anyways)

naming convention

hmm what to say i am in favor of a convention, and sticking to defaults is always good. - we just have to be careful with some renamings regarding backwards compatibility.

not sure regarding documentation und javadoc