Absorb JSR-305 annotations (after jakarta namespace change)

michael-schnell commented 3 years ago

There was already a pull request in 2018 to absorb the JSR-305 annotations. As we now have the jakarta namespace, it should not be a problem to include them into the code base.

m0mus commented 3 years ago

Can you please provide some justification about the purpose of adding JSR-305 annotations here. What Jakarta specs are planning to use them?

michael-schnell commented 2 years ago

Can you please provide some justification about the purpose of adding JSR-305 annotations here. What Jakarta specs are planning to use them?

I just copy the description from the old PR:

Although JSR 305 was never approved, lots of projects and tools use the ones from com.google.code.findbugs:jsr305 (which also include those from net.jcip:jcip-annotations).

Given that common-annotations-api is the new collective home for javax.annotation, adding these annotations would resolve the split-package issue and allow many projects to continue to build with a simple dependency switch.

Related: spotbugs/spotbugs#421 spotbugs/spotbugs#698

Looking at Maven Central (https://mvnrepository.com/artifact/com.google.code.findbugs/jsr305/3.0.2 ) you will see that the "jakarta.annotation" JSR 305extension is used by around 10,000 other libaries. So it would be a huge benefit for the community to finally include them into the code base where they should have been since 2006.

m0mus commented 2 years ago

We already added @Nonnull and @Nullable annotations, see https://github.com/eclipse-ee4j/common-annotations-api/pull/90 They are the most used ones. Is there are reason to add the rest of annotations which are not used often or not used at all?

michael-schnell commented 2 years ago

They are the most used ones. Is there are reason to add the rest of annotations which are not used often or not used at all?

I think we should discuss it exactly the other way round: What is the problem with including something that is already used by 10,000 other libaries? It is a wide spread library that is currently in the same package from the javax namespace as the rest of the annotations.

What are your arguments against it? What are your statistics about "not used often or not used at all"? I think almost 10.000 usages is a lot and not "not often" or "not used at all".

lukasj commented 2 years ago

License - I have found no single file with license header in this particular PR.

Bean Validation - they offer similar annotations at Runtime retention. Why some of them should be duplicated here?

m0mus commented 2 years ago

I am not against it, I am trying to understand why we should do it. It's difficult because JSR-305 is out of Jakarta EE scope. My current understanding is that we don't need those annotations in Jakarta EE. It's potentially needed in other projects like FindBugs. The 10000 number you mentioned above is related FindBugs. But FindBugs is dead. How it will support Jakarta Annotations if we merge it then? SpotBugs is its successor. Is there any guarantee that it will support Jakarta Annotations? Adoption would be good for us.

michael-schnell commented 2 years ago

I am not against it, I am trying to understand why we should do it. It's difficult because JSR-305 is out of Jakarta EE scope. My current understanding is that we don't need those annotations in Jakarta EE. It's potentially needed in other projects like FindBugs. The 10000 number you mentioned above is related FindBugs. But FindBugs is dead. How it will support Jakarta Annotations if we merge it then? SpotBugs is its successor. Is there any guarantee that it will support Jakarta Annotations? Adoption would be good for us.

From my understanding the purpose of the Jakarta project is to standardize things and not only to convert 1:1 the old "javax" JEE scope. In the past it was a often a big problem with the JCP process that useful things didn't make it into the standard, because some large companies had their own hidden agenda and voted against good community suggestions. Now that Jakarta is a community project, it's a big chance to heal things that went wrong in the past.

The libraries using the jsr305.jar are not necessarily using Findbugs at all, as the "javax" annotations are completely independent of it. The primary goal of the annotations is to enhance the documentation in the source code. You might use tools like Findbugs, Spotbugs or Sonar to do some sort of code analysis based on the annotations, but this is fully optional.

Let me give you some examples:

The "@Immutable" annotation is extremely helpful in cases where you cannot make fields of a class final, but still want to dokument that the class is immutable by how it's designed. This is not always obvious to the user of a class, but a very valuable information.
Or let's take "@ThreadSafe"/"@NotThreadSafe": How often did you ask yourself "Is this class thread safe?"? The annotations alone (without any checker) provide important informations about the code.

michael-schnell commented 2 years ago

License - I have found no single file with license header in this particular PR.

I took the code 1:1 as it was from the original JSR. As there was no explicit license attached, my assumption is that the contribution is based upon previous work and is covered by the same license all approved JSRs were licensed under. So it should be possible to simply apply the standard Jakarta license.

Bean Validation - they offer similar annotations at Runtime retention. Why some of them should be duplicated here?

I think bean validation is more about checking something actively and these annotations are more about documenting and (optionally) allowing tools to do a static code analysis based on them. But it might be a good idea to look at them in more detail and maybe move some of them into the bean validation part.

This raises the question, why you included @Nonnull - here. There is already a "@NotNull" annotation in the validation namespace which has the same meaning.

m0mus commented 2 years ago

About the license:

I see that some code is licensed under Creative Commons Attribution License (http://creativecommons.org/licenses/by/2.5) which should by fine
Other code might be licensed under Simplified BSD License, but it's not clear. I found it in JSR-305 discussion group https://groups.google.com/g/jsr-305/c/gQWGmiWMjE8/m/YeN_zcYt1uYJ.

Licenses must be clarified and proper headers added. I don't know are these licenses compatible with EPL 2.0 used by this spec. @ivargrimstad, can someone from the Eclipse Foundation help here?

ivargrimstad commented 2 years ago

Licenses must be clarified and proper headers added. I don't know are these licenses compatible with EPL 2.0 used by this spec. @ivargrimstad, can someone from the Eclipse Foundation help here?

I have sent an email to the license experts for advice.

waynebeaton commented 2 years ago

I took the code 1:1 as it was from the original JSR.

Do I correctly interpret this statement as meaning that you copied and pasted content from the original JSR?

Based on the tone, I'm going to assume from here that the answer to my question is yes.

As there was no explicit license attached, my assumption is that the contribution is based upon previous work and is covered by the same license all approved JSRs were licensed under.

Note that, when content has no explicit license, you can't use it (with no license, you literally have not been given any permission from the copyright holder to use the content in any way).

You need to create a CQ so that the IP team can have a look. In the CQ, provide a link to the original source of the content. Maybe the IP Team can it sort out.

You'll notice that we have a bunch of "JSR 305" CQs. These are (I believe in all cases) project teams requesting that they be able to use one implementation or another of JSR 305 as Third-Party content. Sorting out a consistent story with regard to licensing of this particular content has been a big challenge; but since the library is used for "building and testing" it gets approved as a "works with" dependency.

Anyway... implementing the annotations described by JSR 305 is fine. Whether or not copying somebody else's implementation is possible is contingent to the licensing terms of the content. And, again, if something is not explicitly licensed, then we have to assume that no rights have been conveyed. FWIW, out best guess is that the JSR 305 annotations are LGPL.

If you want this to be included, then my recommendation is that you start over and implement the annotations from scratch.

So it should be possible to simply apply the standard Jakarta license.

Unlikely. Unless something is explicitly licensed under terms that explicitly allow this, you cannot slap terms on somebody else's content (if we discovered, for example, that it is MIT licensed, then we have some options).

michael-schnell commented 2 years ago

I contacted William Pugh (Initiator of the JSR) and Michael Ernst (Expert group member). It seems that Michael Pugh does not answer any mails related to the JSR, so the chance is close to zero to get a confirmation from him to include the code.

Therefore I will cancel the PR as it seems hopeless to get this topic done.

jakartaee / common-annotations-api

Absorb JSR-305 annotations (after jakarta namespace change) #91