Define rawtype API compatibility strategy

[lukaseder]

A very interesting compile time backwards incompatibility has been introduced between jOOQ 3.14 and 3.15 in an area that has not been given any attention to, so far (in 12 years of jOOQ!): What happens when users use rawtypes of jOOQ API.

A customer has been using:

// Some raw type
Table table = DSL.table("");

// This compiled in jOOQ 3.14, but not in jOOQ 3.15
Optional<Field> optionalfield = Arrays.stream(table.fields())
        .filter(field -> field.getName().equalsIgnoreCase("")).findFirst();

The problem is table.fields(), which resolved to:

• jOOQ 3.14: TableLike<R>.fields(): Field<?>[]
• jOOQ 3.15: Fields.fields(): Field<?>[]

Without a covariant override in TableLike<R> (which is generic), the method is now no longer affected by the table expression's raw-typed-ness, and thus always returns Field<?>[], when it used to return Field[].

While this is clearly a backwards incompatibility that can be solved in one of 2 ways:

• By re-adding covariant overrides to all (generic) Fields subtypes
• By making Fields generic: Fields<T> (even if the type variable is never used!)

Both options are equally unappealing. The third option is:

• Do not make any rawtype backwards compatibility guarantees of this kind. After all, using raw types is always a hack and never recommended practice.

[lukaseder]

After giving this more thought, I don't want to fix this. We've broken compatibility numerous times by accident for raw type usage, and that's fine, because there was already a compilation warning before.

So, this task is about documenting jOOQ's stance here: https://www.jooq.org/doc/latest/manual/getting-started/semantic-versioning/