Question about versionning ?

[sbernard31]

I would like know what kind of guarantee (or best effort) we will(want to) try to achieve about versioning.

My general expectation is :

• increment revision number is just bug fix (not API changes)
• increment minor means potential new API but backward compatibility is guarantee
• increment major means we can change everything.

About supported java version, it seems obvious to me that we should not change it for revision increment and we could change it for major. For minor I don't know ? 🤔

Eclipse defines constraints which are pretty much what I exposed above but I guess this is mainly for eclipse bundle targeting eclipse platform.

Here is some documentation about Evolving Java-based APIs

I know eclipse provide API Tools to ensure there is no API break but If I remember well this is Eclipse bundle oriented.

I don't know if there is the same kind of tool that we could use to ensure we don't break API (for revision and minor increment)

[boaks]

FMPOV:
There are not too many features really missing, so we will try to fit them into the minor version.
At least, as long, as that works.
After some time, I guess we will go to focus more and more on the usage within cloud-scenarios, that will pull java 11 and some other stuff, as the long awaited async credentials API. With that I guess we will start Californium 3.0.0 and then provide only bugfixes for the 2.0.0 as long as we can.
That's at least my plan.

[sbernard31]

Here some maven tooling about checking API break :

• https://siom79.github.io/japicmp/
• https://revapi.org/modules/revapi-maven-plugin/

(without maven integration : https://github.com/lvc/japi-compliance-checker)

[rogierc]

The Mule CoAP Connector uses Californium and Mule. Mule has a rather slow Java upgrade cycle because of the large installed base. (Mule 4, that abandons java 7 and uses java 8 only, is just released in 2018).

So, backward compatibility with Java 8 is desirable here.

[boaks]

From my side I don't plan large recoding towards java 11 language features.
My intention is more:

• using new cryptography functions (which are then marked as not supported for java versions, which don't support them, as AES/GCM already does).
• focus the test on using java11

[sbernard31]

#1146 (comment) reveals there is a kind of ambiguity about what we call "API".

Because of my experience in eclipse plugin development, my naive understanding was that every public/protected stuff is part of the API.

This is not exactly true as in eclipse plugin development, you can hide package from the API. (e.g. my.package.internal could be exclude from the API)

So in our case, we don't have this kind of naming convention, so as a user how could I know what is API and what is not ?

[boaks]

FMPOV, the API is somehow unsharp. I would go for include some obvious stuff, frequently used. But exclude the stuff, which is only used when patching the sources.

I would consider this list as API:
element-connector: mostly all
scandium: all interfaces intended to be implemented by custom code, all enum to be used for config, the DTLSConnector and DtlsConnectorConfig.
core: all interfaces intended to be implemented by custom code, all enum to be used for config,
package org.eclipse.californium.core, org.eclipse.californium.core.coap, org.eclipse.californium.core.network, org.eclipse.californium.core.network.config.

[sbernard31]

FMPOV, the API is somehow unsharp

This idea disturbing me a little 🤔

Maybe we can clean packages, moving all what we don't consider as part of the API in "internal" naming package and start a 3.0 ?

[sbernard31]

I try to explain a little why I'm disturbed by this idea.

My feeling is that the benefits of semantic versioning is that when you integrate a component semantically versionned you know exactly what to expect.

• minor or revision number change means "OK I can just integrate the new version this should work"
• major change means "I will probably need time to adapt my code and test if behavior changed".

If we can not provide a clear API perimeter, I'm not sure using semantic versioning make sense 🤔

[boaks]

FMPOV, we can do it "academically", with extra packages (and a lot of work). Or "pragmatically", consider, what is used by users of the library without patching the source. And even if we're wrong, we could then "fix" an API break on "demand" (some work). Over the last months (even years), only the "String/byte[]" PSK-identity break was blamed, the most other stuff seems to haven't hurt too much.
For me it's much more important, that the versions are tested quiet a lot, and bugs are mainly fixed very fast.

[sbernard31]

I don't understand what you call "patching source"...
If a class is public and there is not clear "claim" of what is part of API and what is not.
This is not "patching source" this is just an unexpected reused from you perspective.

"Being pragmatical", what I understand here is no guarantee, just best effort.
In that case as a user I prefer that the library increment its major number or clealy claim semantic versioning is not used.

By the way what you call the "academically" way, is the only "pragmatic" way that allow so many eclipse bundles with so many versions work together.

For me it's much more important, that the versions are tested quiet a lot, and bugs are mainly fixed very fast.

This is clearly a false dilemma.

[boaks]

I don't understand what you call "patching source"...

An example would be the added "final" for a protected Handshaker field. Though I don't see, that some can implement/inject his own Implementation (at least, if not the DTLSConnector is derived and a lot of stuff is reimplemented, that's what I would call patching). So I don't think, that someone gets affected by that change.

[boaks]

By the way what you call the "academically" way, is the only "pragmatic" way that allow so many eclipse bundles with so many versions work together.

Let me guess, there are also "many working on that" and not only "with".

[boaks]

This is clearly a false dilemma.

Either spending time "clarifying the API" or "fixing Bugs" is a false dilemma?
Or do you mean, that some of the "internal API" changes are not required and therefore should not be changed?

[sbernard31]

Let me guess, there are also "many working on that" and not only "with".

Yes, It seems to me this is a necessary but not sufficient condition. My point is this is not just an "academic" position.

You said :

For me it's much more important, that the versions are tested quiet a lot, and bugs are mainly fixed very fast

This sounds like : do you prefer a "not buggy application" or "semantic versioning" ?
This sounds like a false dilemma because this is not binary choice.

About the cost, with tooling and moving "not part of the API" class in internal.* package, I'm not sure this is so costly. User can of course ask to move "internal" class in the API if needed (this generally don't break backward compatibility).

Anyway again, If the conclusion of this discussion is : we don't want to invest time on checking API, I'm OK with that. I just prefer to increment the major version to be clear about that.

[sophokles73]

Everybody,

FMPOV there is truth in all arguments you have brought up so far :-)
There are some constraints defined by the Eclipse Development Process that we need to comply with in any case. One of them is that we are using semantic versioning and thus, if we break public API in a way that is not backwards compatible, we need to increase the major version number.

That said, the EDP does not dictate what is to be considered public API, i.e. we are free to define which packages we consider public and which we consider private. There is no automatism that says that every public (in a Java sense) class/method is to be considered public API.

I believe that we should make a conscious decision for each package and mark them accordingly. This might lead to situations where we need to introduce changes in a less invasive way, e.g. by means of overloaded methods or copied code. But the rules are clear, we follow semantic versioning. You have been putting a lot of work into Cf 2.0.0 during the last three years, so I would not expect too many such issues showing up in the first place. Where they do, we can decide on how to handle them, i.e. as described above or by means of starting work on a 3.0.0 version.

[boaks]

@sbernard31

Please, just start with introducing one of your proposed tools, if they allow to exclude some stuff from the check. With that, every PR must pass this, and I guess, if a API is violated according this test, the change will be either withdrawn, or concluded as being not part of the public API and therefore added to the excluded stuff.
We can even decide, that such a PR requires a mail to cf-dev and should be at least open for a week to discus, if someone is affected from that break.

Personally I don't want to spent my time into clarify the API now ahead or API checking tools.

[sbernard31]

I'm currently playing with it as this will at least useful for revision version.
The first result is that we already break the API a lot, but we also have inconsistent API (like public class with public attribute typed with private class)

[sbernard31]

I create a PR which introduces API check tooling (revapi) : #1168

[boaks]

@rogierc
@sbernard31

The Release 2.5 is upcoming. My impression of that past month was, that is time to switch to Californium 3.0 in order to get rid of the "deprecations".

One question which is left open:
Should the 3er be based on Java 8? Or on Java 11?

[sbernard31]

Should the 3er be based on Java 8? Or on Java 11?

Good question, unfortunately I haven't good answer ...

My guess is the older JVM we support the more our library can be reused.
But of course with this kind of thinking we could be stuck with java 7 for ever...
AFIAK, the main reason to support java7 was for android compatibility.
I'm clearly not an expert about android, so I don't know which java version would be more appropriate but last time I try to understand this, my conclusion was java7 is OK and java8 is partially OK. (There is some news but still not clear to me)

Another question which could maybe help to decide, why could be the benefits to be based on Java 8 or 11 ?

[boaks]

With java 11 it's easier to use the new cipher stuff.
At least, I personally run and build Californium in the meantime mainly with java 11.
For Android I think, I should check, what's possible.

[sbernard31]

I opened an issue to talk about this on Leshan project. (eclipse-leshan/leshan#924)

[sbernard31]

Do you think this is possible to provides code which is compatible with Java7 (or 8 if needed) and only require java 11 when new cipher is used ? (I guess this is pretty much the way you do now ?)
Or you mean that you can not do that anymore ?

[boaks]

My feeling is just, that it takes more and more time to build and test with java 7, java 8 and java 11 (and java 15).
My intention is more, to focus on one (java 11). The cipher stuff so far works with the current approach.

[sbernard31]

But If we focus java 11 we lost Android support ?

I probably missed something but if we target java 7 (or 8), also supporting more recent one should not be a big deal as generally java is more or less backward compatibility. (but I suppose you face concrete issue which make this idea not so true?)

If the idea above ☝️ is to expensive, because we multiply java version to test, maybe a trade-off could be to target a minimal java version for android + check java compatibility for only one java LTS support. (e.g target java 7 + compatibility check for java11, or target java 8 + compatibility check for java 11)

[boaks]

But If we focus java 11 we lost Android support ?

That's the downside,

I probably missed something but if we target java 7 (or 8),

It's just my impression, that it gets harder and harder to build with that. And I'm not sure, how many are really still using these versions.

target java 8 + compatibility check for java 11

That may be the outcome :-).

[sbernard31]

Here is java release roadmap :

• Adopt OpenJDK Release Roadmap
• Oracle Java SE Product Releases

Java 8 will be supported for a long time (2026/2030)

If Java 8 is OK for android(which is not clear to me) and if we really want to support only one JDK, java 8 could be the best choice.

[sbernard31]

I'm asking myself how animal-sniffer could be able to support android java 8 support and especially desugaring.
This thread could help to better understand : google/guava#4005
=> gummy-bears could be a solution.

[boaks]

@sbernard31

Just to say: I don't plan something as a "decision in the next days/weeks".

But I would like to release 2.5.0 on Thursday. So, if possible, can we focus on issue #1443 and PR #1442 ?

[boaks]

I had a look over the links.

For me, it looks for java 8 as base.

(But, again, even if java 8 is the base, I will focus on my own tests on executing it with java 11.)