Re: [jakarta.ee-spec.committee] Jakarta EE Scope Statements Guidelines

[Wayne Beaton <wayne.beaton@xxxxxxxxxxxxxxxxxxxxxx>]

Whether or not the scope statements are adequate is actually up to the specification committee. From the specification committee's point of view, the question is whether or not the scope reasonably constrains the range of potentially committed essential claims. All work done by the project as it moves forward must be in-scope; e.g. all plans must define work that is in-scope, and all progress and release reviews must validate that the content produced by the project is in-scope.

Unfortunately, I don't think that there is any "cookie cutter" answer to creating scope statements. When I first started looking at this, I tried to answer (as concisely as possible) "what is a servlet?" and then more generally, "what does the servlet specification define?" and went from there. The "What is a Servlet?" and "What is a Servlet Container?" bits in the Servlet specification are a good start. 

IMHO, the scope statement must be no more than a few sentences in length to be useful. Any attempt to be especially precise or "legal" is doomed to grow in size enough to rival the specification document itself.

The recommendations in the blog post are based on my experience with creating scope statements for projects. It would, I believe, be a good exercise to collect the handful of statements that Ivar and I have crafted and ask the specification committee discuss them on a (near) future call.

 

Will the TCKs be part of the Spec Projects (when they're eventually split out of the CTS, or like Jakarta Mail are already separate)?

From the blog post:

Like the specification scope, the project scope should be aspirational. In this regard, the specification project is responsible for the particular specification in perpetuity. Further the related artifacts, like APIs and TCKs can be in scope without actually being managed by the project right now.

 

Today, for example, most of the TCKs for the Jakarta EE specifications are rolled into the Jakarta EE TCK project. But, over time, this single monster TCK may be broken up and individual TCKs moved to corresponding specification projects. Or not. The point is that regardless of where the technical artifacts are currently maintained, they may one day be part of the specification project, so they are in scope.

Unless there is a compelling reason to keep them separate, the TCKs are in-scope for specification projects. That's not to say that they must be moved to the specification projects by any particular date.

HTH,

Wayne

 

On Wed, Apr 17, 2019 at 6:09 PM Bill Shannon <bill.shannon@xxxxxxxxxx> wrote:

Thanks for the pointer.  I feel like I'm only really going to know what a good scope statement is after reviewing a bunch of scope statements.  I took a crack at it for Jakarta Mail, but I don't know if I did it right! :-)

Do we want to request that the Project Leads for each of the Specification Projects send a draft scope statement to the Specification Committee, which will collect them together and review them all at once, sending feedback to the Project Leads?  (Although the Specification Projects don't really exist yet because we haven't converted some of the existing projects into Specification Projects.)

Or do you feel like you can review them one at a time as they come in?  (Maybe Wayne can do that, but I can't!)

I guess we're supposed to use the project tracker to know what's ready for review.

It sounds like we need to vote on each scope statement.  How are we going to keep track of which scope statements have been approved?  Meeting minutes?  Closing the corresponding issues?

In addition to the Specification Committee approving the new scope statements, do the projects also need to go through a formal Eclipse process to update the scope for a project?  If so, how will we track that that's been done?

As usual, I'm just trying to understand what the process is for getting to an approved set of scope statements for our projects.


Finally, I have to ask once again...

Will the TCKs be part of the Spec Projects (when they're eventually split out of the CTS, or like Jakarta Mail are already separate)?

Or will they have to be in a different project, e.g., because they'll need to use a different license?

Last I heard, they needed to be separate, but I'd like confirmation.  (The Jakarta Mail TCK will need to be moved, for example.)

Ivar Grimstad wrote on 4/17/19 9:17 AM:

Here is an excerpt from Wayne't blog regarding scope statements. The entire blog post can be found here: https://waynebeaton.wordpress.com/2019/04/08/specification-scope-in-jakarta-ee/

Ivar

Regarding scope, the EFSP states:

Among other things, the Scope of a Specification Project is intended to inform companies and individuals so they can determine whether or not to contribute to the Specification. Since a change in Scope may change the nature of the contribution to the project, a change to a Specification Project’s Scope must be approved by a Super-majority of the Specification Committee.

As a general rule, a scope statement should not be too precise. Rather, it should describe the intention of the specification in broad terms. Think of the scope statement as an executive summary or “elevator pitch”.

Elevator pitch: You have fifteen seconds before the elevator doors open on your floor; tell me about the problem your specification addresses.

The scope statement must answer the question: what does an implementation of this specification do? The scope statement must be aspirational rather than attempt to capture any particular state at any particular point-in-time. A scope statement must not focus on the work planned for any particular version of the specification, but rather, define the problem space that the specification is intended to address.

For example:

Jakarta Batch provides describes a means for executing and managing batch processes in Jakarta EE applications.

and:

Jakarta Message Service describes a means for Jakarta EE applications to create, send, and receive messages via loosely coupled, reliable asynchronous communication services.

For the scope statement, you can assume that the reader has a rudimentary understanding of the field. It’s reasonable, for example, to expect the reader to understand what “batch processing” means.

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

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

--

Wayne Beaton

Director of Open Source Projects | Eclipse Foundation, Inc.