Skip to main content
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [jakarta.ee-spec.committee] Interaction Between Code-First and Specifications
The idea of "code-first" is a good one but figuring out how that is going to be coordinated with writing/updating a written specification and API seems to be a stumbling point.

My suggestion is that proposals for new functionality in the specifications and APIs must be demonstrated with code somewhere (either by a vendor outside the Jakarta EE WG or as a skunk-works project under the Jakarta EE WG) and reviewed before being considered for addition to the specification. If it works and everyone thinks it makes sense to add it to the specification, then its added. 

The demonstration might be just a sampling of code or maybe someone did a full implementation integrated with their Jakarta EE product.  Either way, code will have been written and demonstrated to work before it is even considered for inclusion in a specification update.

Once its specified and the TCKs are written than it can be included in implementations.

On Wed, May 30, 2018 at 4:59 PM, Mike Milinkovich <mike.milinkovich@xxxxxxxxxxxxxxxxxxxxxx> wrote:

All,

I have decided it is time for a new thread, as I am starting to get lost in "Recent Edits".

Recently Bill Shannon, Ivar Grimstad, Steve Millidge and Scott Stark had some comments on the interaction between the code first approach and the specification process requirements. For the record, I think Ivar's email is so spot-on we might want to add it to the document as a use case to help elaborate on the requirements.

Bill Shannon:

  • ... 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?
  • Proposed Resolution: 
    • The definition of a Specification Project should be refined to recognize that the Specification Document and the TCK will be done in separate Eclipse project managed under the same PMC.
    • Now that there is no single Reference Implementation, we need to fix that in the definition as well.

Steve Millidge:

  • I think is the root of my confusion the specification process discussions seem to be pushing back towards the spec first approach with Expert Groups etc.
  • Proposed Resolution: If you have any specific suggestions on how to improve the wording, please suggest or comment on the document. Personally, I don't think that the spec process is pushing back on code first at all. At some point you still have to take IP from the code and turn it into a Specification, and that's what we're working on. But I fully admit that I'm perhaps too close to the wording, and will happily take suggestions to make that clearer.

Scott Stark:

  • ...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.
  • Proposed Resolution: I am not seeing this. Ivar makes it clear that you end up with a formal specification document and that other implementations would be expected to move to reflect those updates.

HTH

--
Mike Milinkovich
mike.milinkovich@eclipse-foundation.org
(m) +1.613.220.3223


_______________________________________________
jakarta.ee-spec.committee mailing list
jakarta.ee-spec.committee@eclipse.org
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/jakarta.ee-spec.committee


Back to the top