Re: [jakarta.ee-spec.committee] Recent Edits

[Scott Stark <sstark@xxxxxxxxxx>]

That is a viable approach, but this looks to be in conflict with the requirement that one be able to create a clean room implementation from the spec document due to the references to the JavaDoc produced from the external API code.

I think Bill makes a good point about the TCK being a separate project from the spec project. I think it would be ideal if the spec document would would make use of a set of common annotations to define the expected TCK assertions to facilitate the interaction between the two.

On Wed, May 30, 2018 at 1:49 AM, Ivar Grimstad <ivar.grimstad@xxxxxxxxx> wrote:

Hi,

I think we are confused since we are so used to thinking "spec first", while we now should be thinking "code first". 

In the spec-first approach, it makes perfect sense to group the API with the spec. 

But when we turn around to code-first, I think they should/must be separated.

Consider the following scenario for a code-first approach:

Let's say Apache CXF has some cool features that partly overlap with some features of RESTEasy. Jersey may or may not have these features.

The JAX-RS API Project

1. Decides to extract the best parts from the implementations and produce a standard API for them.

2. Release JAX-RS 3.0

3. Propose to the Jakarta EE Specification Committee to standardize through Jakarta EE

    a. A EE4J project (such as JAX-RS API project) would go through the EE4J PMC

    b. A standalone Eclipse Foundation API project would go through their PMC

    c. A project outside the Eclipse Foundation (e.g. Bean Validation) would go through their equivalent to the PMC

The Jakarta EE Specification Committee

1. Approves the suggestion (or suggest changes or decline...)

2. If approved, mandate the Jakarta EE Spec project for JAX-RS to produce the specification

The Jakarta EE JAX-RS Specification Project

1. Produce the specification document which includes:

   a. A human readable description of the API with references to the API JavaDoc

   b. Define what MUST, SHOULD, COULD, SHOULD NOT etc. be implemented in order to comply with the specification

   c. Assertions backing up the MUSTs, SHOULDs, COULDs and SHOULD NOTs on an agreed up format to form the basis by the TCK

The JAX-RS TCK Project

1. Use the assertions from the spec to create/update the JAX-RS TCK

2. Seek approval that the TCK does what it is supposed to from the Jakarta EE Specification Committee

The Implementation projects (may or may not be Eclipse projects)

1. Adjust their implementations to implement the API

2. Test their implementation against the TCK

Whether, or not, JAX-RS 3.0 should be a part of Jakarta EE X is up to the platform project/Specification Committee to decide.

Does it make sense, or am I way off?

Ivar

On Wed, May 30, 2018 at 12:08 AM Bill Shannon <bill.shannon@xxxxxxxxxx> wrote:

I'm starting to become concerned/confused about this as well.

I think we were previously expecting that a specification project would manage the specification document, the source code for the API classes, and the source code for the TCK.  Assuming we need special rules for specification projects, do we really want those special rules to apply to the API and TCK, which after all are just source code projects?

The API classes are hard because they mix specification with (varying amounts of) implementation.  But none of the IP issues for the spec apply to the TCK, right?  Maybe the TCKs should be in separate code projects that follow the normal EDP rules?