eclipsefdn / efsp Goto Github PK

From @rmonson (moved from #1)

I would recommend removing the following "may also be referred to as a Maintenance Release" as it confuses things especially later in the document when you use only the term "service" . I know why its there but I think we have to settle on "Service" or "Maintenance Release" but not both.

I would add something like this to the Service release definition to ensure that it limited to very minor changes.

"A Service Release does not include any significant new features and/or breaking changes"

Sorry, wrong link, I created jakartaee/JESP#5 instead.

If a new project is truly being created, then the Restructuring Review can be combined with a Creation Review. Nothing to see here.

If an existing project is being changed into a Specification Project, then nothing new is being created. Instead, the nature of an existing project is being changed. I don't believe that the EFSP is strictly at odds with this, but there may be a hole with regard to the Specification Committee approval of the "creation".

Intellectual property grants that flow from a progress or release review are based on the content as it exists at the time it is presented to the specification committee for approval.

Specifically, a complete build of the specification content (a "milestone" build of the specification version) must be delivered to the EMO and specification committee as the subject of a progress or release review. The approvals that are obtained as part of the review and intellectual property grants that flow from it apply only to that build.

The project team may continue to innovate and otherwise evolve the project content in parallel. Intellectual property grants associated with that parallel work must be resolved via a future review.

Q: must the milestone build that is the subject of the progress or release review persist indefinitely?

The EFSP is silent on the notion of errata.

Below are some thoughts, put forward with the intention of initiating a discussion. Nothing here is a policy statement.

The notion of a service release extends the definition provided by the Eclipse Foundation. A service release contains "bug fixes" for an earlier release for which the project team has engaged in the full development cycle (including both a plan and release review). "Bug fixes" are generally considered to be updates to existing functionality. From the perspective of specification development, fixing a bug may subtly change intention, so the specification process requires that the project team engage in a full review for every service release.

Errata are smaller than service releases. In general, an errata is a change that is intended to clarify intention, not change it. This may include minor typographical changes, the inclusion of small amounts of clarifying text, or updates to a TCK exclusion list (just examples). Errata must never change intention. Errata must not, for example, define any new behaviour or change the signature of an API. As a general rule, an errata should never break a existing Compatible Implementation.

The specification committee is the arbitrator of what differentiates errata from service release. My strong suggestion is that the specification committee provide guidance to help specification project teams differentiate. It would be the responsibility of the specification committee to put some means in place to identify when an errata crosses the line to service release and mitigate.

Suggestions:

A specification project may maintain an errata sheet as a live document, coupled but separate from the Final Specification document that is updated as necessary by the project team without formal ceremony. That is, there is no formal notion of an "Errata Release", just an Errata list.

We add a notion of Errata Release to the EFSP.

Thoughts?

A specification version should be "locked down" during a specification committee ballot. Specifically, this means that the content should not be changed.

It would, however, add unnecessary hardship to require that a ballot be restarted for minor fixes like typos that do not change the semantic intent of the text. A change that does change semantic intent would invalidate the ballot and corresponding review, and require that the process be restarted.

What constitutes a minor fix may be ambiguous, so it is left to the Specification Committee to determine whether or not a fix qualifies. The specific mechanism will be left to the discretion of the committee.

As some simpler specification projects may either

• not need a TCK, or
• start out without needing that notion, but later develop the need,

We should consider revising the EFSP to allow the "no TCK defined" track.

Add the following:

1. Unless otherwise stated in a specialization of the EFSP, the default length for all review periods is 14 days. During that time, any member of a specification committee can request an extension of the review period to 30 days to permit them additional time for intellectual property reviews.
2. No Review period can be shorter than 7 days, and no specialization of the EFSP is permitted to reduce the review period to less than 7 days.

When used regarding ratification, as in "including the adoption of Specification Versions", the word "adopt" feels unnecessarily confusing. We should just say "including the ratification of Specification Versions"

The definition of Ratified should also be tweaked.

A Specification Version that has been adopted by the Specification Committee and made available under the Eclipse Foundation Specification License to enable the creation and certification of Compatible Implementations.

To be consistent, we should talk about the Specification Version being approved by the Specification Committee.

The EFSP defines Specification as:

A collection of Application Programming Interface (API) definitions, descriptions of semantic behavior, data formats, protocols, and/or other referenced specifications, along with its TCK, intended to enable the development and testing of independent Compatible Implementations.

It's implied, but not explicitly stated that a Specification Document is what provides "descriptions of semantic behavior, data formats, protocols, and/or other referenced specifications".

In concept, a specification is the composition of:

• the description of behavior, formats, and protocols;
• supporting technical artifacts; and
• a means of validating that an implementation conforms to the description of behavior, formats, and protocols.

In practical terms, a specification is, then, the composition of:

• a Specification Document;
• technical artifacts (e.g., an API); and
• a TCK.

Later, the definitions section describes a Specification Version as a specific version of a Specification; we then later further describe it as:

Each Specification Version references specific versions of its constituent artifacts. These artifacts include the Specification Documents, zero or more other Specifications, one or more Compatible Implementations licensed under an Open Source License, and exactly one associated TCK for this Specification.

That is, we add the inclusion of one or more Compatible Implementations.

The diagram shows the TCK and Compatible Implementations as connected, but separate (the relationship appears aggregate rather than composite).

The diagram for Final Specifications near the end of the document suggests/reinforces an aggregate relationship between a Specification Version and a TCK, and a tigher composite relationship between all artifacts for a Final Specification.

To my mind, the Compatible Implementations attached to a Specification Version or Final Specification must always be aggregate; there's not guarantee that any particular Compatible Implementation will persist as long as the Final Specification that references it.

The statements regarding votes of the "strategic members" need to be qualified.

e.g.

Super-majority, including a Super-majority of Strategic Members, is required to approve a Profile Specification.

The intention is that we get a Super-majority of the Strategic Members of the Working Group (not all Eclipse Foundation Strategic Members)

Refer to the process of collecting votes from specification committee members as a ballot rather than a "vote".

Add a note somewhere that the IP Policy is where the patent rights are granted. Any concerns? I don't mean duplicating the text. I just mean a note to "go read this over there"

/cc @mmilinkov

Some specification projects, e.g., OSGi Specification include specifications, TCKs, and implementations in the same project. In the case of the OSGi Specification project, they're all actually in one single Git repository. Factoring that into separate Git repositories owned by separate projects would likely be onerous, and provide no incremental value.

The Eclipse Foundation Development Process supports the notion of releasing a project in parts. Theoretically, a specification project could, then, create many releases of an implementation without creating any new final specifications. Were these implementations part of a regular Eclipse project, they would have to engage in a review only annually.

I took only a quick look at the IP Policy. I believe that it supports a notion of a specification project releasing non-specification content without a release review.

e.g.:

Pursuant to the Eclipse Foundation Specification Process, each Specification Project will have a series of Check Point Reviews prior to the publication of a Final Specification.

I'm interpreting this to mean that a review (a release review is a kind of check point review) is only required when the release includes a new final specification. I'll need to have a closer look to make sure that there are not other "gotchas".

The EFSP more tightly couples Specification Projects and releases.

e.g.:

Reviews are required for all Releases of a Specification Project.

We may be able to squint and say that this doesn't apply to implementations released by a specification project, and the removal of the requirement for release reviews for service releases (#29), may actually make this a non-problem; but it would be better to make this as clear as possible. This needs to be fixed and now seems like a good time to fix it.

/cc @paulbuck
/cc @bjhargrave

By way of background, BJ, I'm drafting an update to the EFSP (see #33). I'll contact you via email with more information shortly.

Version 1.0 does states only that a super-majority vote is required. It does not specify how a vote is undertaken.

We discussed today that we should add:

• Minimum 14 days voting for progress, release, and service release votes;
• Minimum 7 days voting for plan and creation approval.

We reasoned that progress, release, and service release votes have implications regarding intellectual property and so will require more time for legal review. Planning and creation votes do not have direct intellectual property implications and so can default to standard seven day period that we use for everything else.

Theoretically, a service release vote that does not have IP implications could be shorter, but it may be difficult to consistently determine whether or not a service releases has IP implications.

We may consider adding a "notwithstanding clause" that gives the specification committee the ability to override the standard voting minimums under special circumstances.

The specification committee should also be able to reset the clock or otherwise move a vote deadline to give project teams an opportunity to resolve issues before a vote concludes.

The definition of Compatible Implementation is, I think, incorrect.

A Compatible Implementation must fully implement all non-optional elements of a Specification Version, must not extend the API (no supersetting), and must fulfill all the requirements of the corresponding TCK. ...

Compatible Implementations must be based on a Final Specification.

Note that, with #42, I expect that we're yanking out the requirements regarding non-optional elements, so I'm thinking that we change this to:

A Compatible Implementation must fulfill all requirements of a Final Specification including all requirements of the corresponding TCK, and must not extend the API (no supersetting). ...

The Scope must be well-defined and fall within the mission and scope of the corresponding Top-Level Project.

Requiring that every development cycle have at least one progress review and finish with a release review adds a significant amount of time to the process that makes it difficult to evolve a specification rapidly. Rather than require a minimum number of progress reviews, let's consider making it more time based.

e.g., a specification project must engage in a Progress Review at least every six months while engaged in active development (after the completion of a Creation Review or Plan Review; and before the Release Review). This needs to be worded better.

Moved from #24.

The EFSP it says "A Super-majority, including a Super-majority of the Strategic Members of the Working Group, is required to approve a Profile Specification.". The language refers to "Strategic Members of the Working Group". Not all working groups have Strategic Members, or an equivalent (AsciiDoc or MicroProfile, for example, only have one level of corporate membership).

That there is not necessary even an equivalent membership level to which we can map, I'm thinking that we should just yank this from the EFSP and leave it to individual working groups to add this as an extra requirement should they choose to do so.

What do you think @mmilinkov and @paulbuck ?

In the "Approvals" section, we state that a ballot is required for a service release (last bullet).

Later in the document, we state that a release review is not required for a service release.

Strictly speaking, these statements are consistent. But there is potential for confusion when the latter statement is read out of context.

The Jakarta EE Specification Committee was attempting to clarify how to process Service Releases for Specifications. This was being done via the following two PRs:

JESP Update: jakartaee/jakarta.ee#1050
Ops Guide Update: jakartaee/jakarta.ee#1047

In the JESP Update PR, it was pointed out by Wayne that the Approvals section of the EFSP indicates that a Super Majority Vote is required for Service Releases.

But, in the Specification Version LIfecycle section of the EFSP, the first sentence indicates that the lifecycle as defined does not apply to Service Releases:
To produce a Specification Version (with the exception of Service Releases) a Specification Team must engage in a formal Release Cycle under the supervision of the Project Management Committee (PMC) and the Specification Committee.

Also, in the Service Release section of the EFSP, there is this confusing statement:
A Specification Team must have engaged in a successful Release Review for a Major or Minor Release prior to engaging in a Service Release. No Progress Review is required for a Service Release; the Specification Team must, however, engage in a successful Release Review.

This section is what we were attempting to clarify and simplify via the JESP Update PR.

Our interpretation of these inconsistencies is that the "Service Release" reference in the Approvals section was a mistake. If Service Releases have to follow the exact same, detailed process as the other type of releases, then why did we insert these "exception" clauses in those two other sections?

Also, there are examples of producing Service Releases without such a formal process. We have produced Service Releases for both TCKs and APIs for Jakarta EE. And, since the APIs contain Javadoc, which is considered part of the "Specification", then we already have a simpler process being used to produce Service Releases for Specifications. We just don't have it properly documented.

We need to quickly come to a conclusion on this interpretation since these Service Releases are coming into play for Jakarta EE 9.1. We are aware of at least four Spec Projects which want to correct their Javadoc for 9.1 via Service Releases for their respective API artifacts. The overall Release Plan for 9.1 is targeted for end of January, so we need to resolve this definition quickly. Even if we can't get the EFSP updated and published, if we can get agreement on the direction so that we can make progress with 9.1, that would be appreciated.

There is some potential for confusion regarding who we describe as "early adopters".

Per @bshanon in #15,

I think of the people using the non-final implementations as the early adopters. The people building the implementations are just the implementors. I don't classify them as "early" or "late".

It is intended that the "early adopters" are implementors.

Member Participants have the right to appoint a Participant Representative to every Specification Project that falls under the purview of the Specification Committee.

The intention of a participant representative is to ensure continuity of a member participant's interest. That is, this is a power that a member participant will use to ensure that they have at least one committer on the project to ensure the continued flow of intellectual property grants. If the member participant already has an employee as a committer, then that member participant is considered to already have a participant representative and could not appoint another.

Further, a participant representative becomes a "regular" committer. That is, once appointed, the committer has no special status (if they change employers, for example, they are not automatically retired and--if they are the only committer employed by a particular member participant--that member participant would be able to appoint another participant representative).

Be less prescriptive about the nature of specifications themselves and related artifacts (e.g., the nature of APIs and TCKs).

For example:

A Specification may describe parts as being optional. Optional parts of a Specification must not conflict with one another; it must be possible for a Compatible Implementation to implement all optional parts.

This is the sort of requirement that individual working groups specification committees should impose when it makes sense for them to do so.

My thinking for now is that we completely yank this sort of content out of the EFSP and add it (in one form or another) to the operations guide as examples of the sorts of requirements that specification committees can impose over the process via the own specialization of the process.

The EFSP suggests that a profile may be designated as a platform, but provides no compelling reason to have this designation.

There are two references:

A Specification Committee may, at its discretion, elect to label one or more Profiles as a “Platform”.

and

• A Platform designation (this Super-majority must include a Super-majority of Strategic Members of the Working Group).

IMHO, it adds no value in the general case and should be removed.

By removing this, we are not adding any restriction on the ability of a specification to be labeled a "platform"; since the specification committee gets a vote when a new specification project is created or a new specification is added to an existing project, they effectively have control over the use of the term anyway.

As with other cases, a working group may opt to add this notion into their own specialization of the EFSP.

Am I missing something important @mmilinkov ?

I have started work on EFSP 1.3.

I've created a project board to track the items under consideration.

As I make updates to the source document, I'm capturing a "diff" of the changes here. Note that this document is not automatically updated with every commit to this repostory; updating requires some manual intervention.

The process requires that we establish a committee:

Executive Director convenes a committee (composed primarily, but not exclusively, of representatives from Working Group Specification Committees) and appoints a chairperson.

I have reached out to each of the working groups engaged in specification work and have identified a committee. I will convene the committee in mid August, targeting delivery of the updated process to the board of directors for either their September or October meeting.

Comments on the issues are, of course, welcome at any point.

We need to make it clear that a participant representative is a committer.

More specifically, every committer on a specification project is a participant representative, representing the interests of either a member participant or themselves as an individual participant.

In the case where a member participant is found to be without representation on a specification project, they can appoint a single participant representative. Additional participant representatives may be added via committer election process defined in the EDP and described in the Eclipse Project Handbook.

The process bits in the EFSP are built around a notion of projects being at the center of all things. That is, things like reviews are project level things. According to the EDP, a project may release only parts, so the notion of a single specification project that's used to develop multiple specifications engaging in a release review to create a Final Specification for just one of their specifications is fully supported.

It's the same for creation reviews. Creation reviews are used to create projects. Adding a new specification to an existing specification project is essentially the same as adding new functionality to an existing software project: that is... you're not creating a new project, you're just adding something to an existing one.

When an existing project team decides to start working on a new specification, the specification committee would have to be informed of that intention via a plan review at the beginning of a development cycle.

I don't think that anything in the specification process itself needs to change. But this is a subtlety that will need to be documented in the operations guide.

The Eclipse Foundation TCK license requires that the testing party must:

make TCK test results showing full and complete satisfaction of all requirements of the TCK publicly available on the testing party’s website

It is not entirely clear what is acceptable for the testing party’s website.

Must this be a website under the testing party's commonly used domain name (e.g. ibm.com for IBM). Or it is acceptable that the website and/or its content merely be under the control of the testing party (e.g. a github.io or custom domain GitHub Pages site for an open source project)?

Let's use this as a container, or umbrella bug to address updates to the Eclipse Foundation Specification Process. I'd like to make this a minor revision (so no structural changes).

For this first revision, I'd like to address the following:

• Add consideration of Maintenance Releases; (#1)
• An "Individual Participant" is defined in terms of an "individual Committer", but "individual Committer" is not defined;
• Ensure that it is clear that a "Member Participant" is a member of the Working Group; (#5) and
• Move "The Specification Project creation process" diagram to a supporting document (this diagram feels out of place here).

Is there anything else to address in this iteration?

(copied from Bug 543224)

The definition of "Open Source License" ends with: "This list may be modified with the unanimous approval of the Working Group Steering Committee and the Eclipse Foundation Board of Directors."

What we meant to say is that the unanimous approval of the steering committee is required, followed by approval of the Eclipse Foundation Board of Directors. Approval of the BoD is generally accepted to mean a simple majority.

Potential re-phrasing:

This list may be modified with the unanimous approval of the Working Group Steering Committee, and by a simple majority of the Eclipse Foundation Board of Directors.

/cc @mmilinkov

The "Specification" section does not make who is required to vote clear. The passage just says that a super-majority is required, but it doesn't say of what body:

A Specification that aggregates other Specifications by reference may be designated as a Profile. Profiles do not have to be arranged in unique subsets (i.e. a Specification may appear in more than one Profile). A Super-majority, including a Super-majority of the Strategic Members of the Working Group, is required to approve a Profile Specification. A Specification Committee may, at its discretion, elect to label one or more Profiles as a “Platform”.

The "Approvals" section does indicate that a super-majority of the Specification Committee is required.

Both sections are clear that "this Super-majority must include a Super-majority of Strategic Members of the Working Group".

We have two choices:

1. Remove the highlighted text; or
2. Update the highlighted text to start with "A Super-majority of the Specification Committee".

I'm leaning toward #2. In either case, let's add a link to the "Approvals" section.

Since intellectual property may be implicated in a service release, and reviews are the trigger for committing intellectual property, we need a full review for service releases.

The EFSP currently defines a "Member Participant" as

A Member of the Eclipse Foundation including Solutions Member, Enterprise Member, or Strategic Member (as defined in the Eclipse Foundation Bylaws) that has one or more Committers on a Specification Project.

The membership levels have changed; "Solutions Member, Enterprise Member, or Strategic Member" should be updated to "Strategic and Contributing Member".

The EFSP references the Working Group Participation Agreement. This is an old document and including it may be potentially misleading and confusing.

I'm thinking that, rather than just ripping it out, we replace it with a reference to the "corresponding working group participation agreement" (or something like that).

Does this make sense to you @paulbuck?

In the "Approvals" section, we state that a ballot is required for a service release (last bullet).

Later in the document, we state that a release review is not required for a service release.

Strictly speaking, these statements are consistent. But there is potential for confusion when the latter statement is read out of context.

In the "Approvals" section, we state that a ballot is required for a service release (last bullet).

Later in the document, we state that a release review is not required for a service release.

Strictly speaking, these statements are consistent. But there is potential for confusion when the latter statement is read out of context.

We'll add an "Exceptions" section that states that exceptions to the process may be granted at the sole discretion of the Eclipse Foundation Executive Director based on a recommendation from the Working Group's Specification Committee.

From @kwsutter: Maybe this "DRAFT" can be changed into a doc variable so that it can be modified as part of the final build process for the EFSP? We do that with our MicroProfile spec documents. During our build process, we parameterize the [Draft/Final] version of the release and that is used in our pdf and html generation of the Spec document. Something similar for the EFSP might be nice.

Clarification as to whether a single compatible implementation must implement ALL optional specification aspects is a requirement, or that one or more compatible implementations in union are required to cover all optional specification aspects is needed.

Clarify that progress reviews are required only for major and minor release.

Specifically, no progress review is required in the lead up to a service release.

On the https://www.eclipse.org/projects/efsp/#efsp-version-lifecycle, image "An overview of the Eclipse Foundation Specification Process", the expectation is that Proposal, Plan, Milestone, SpecVersion and Ratified Final Specification all would be represented in oval-ish element, but Plan is not. Can we fix that?

Thanks,
Tanja

The EFSP should reference the requirement for a specification project (or more likely the specification committee) to select a patent license.

I'm thinking that we add Patent License as a term.

Then, we leverage content from the IP Policy for inclusion in the Specification Project section:

At the commencement of each Specification Project, such Specification Project will have a specified and documented Scope, and explicitly select whether they will utilize an Implementation Patent License or a Compatible Patent License as defined in the Eclipse Foundation Intellectual Property Policy. The Scope and choice of Patent License must be made known to the Specification Committee in advance of the initiation of the Ballot to create the Specification Project.

We might add some content to the Specification Committee section to describe the specification committee's responsibility to set a policy regarding the choice of Patent Licenses for the projects operating under their purview. This may be a better fit for the operations guide.

Finally, we should add content from Mike's blog post, On Patents and Specifications to the operations guide.

Avoid prescribing the nature of a TCK. It should be possible, for example, to have a TCK that is entirely documentation. I think that we can get there by changing the definition of TCK from

Software and documented requirements that support...

to

Software and /or documented requirements that support...

We have "created" several specification projects from existing projects via restructuring review. While I believe that doing so is completely onside, it does require a specific interpretation of the process.

I'd like to make this a first class concept.

• An existing project can be turned into a specification project via restructuring review.
• A ballot of the specification committee is required
• The successful restructuring review will serve as the plan review for the first release as a specification project.

When creating a specification project, we need to select a patent license (as described in the IP Policy). We need to ensure that an informed decision is made.

I believe that the specification committee has say in the selection. They may decide that all projects under their purview make a specific selection, or grant flexibility.

This is related to content that needs to be in the working group operation guide (realted to issue 1 in the EFWGP repository).

Did you decide that the TCK must be developed by an Eclipse project?
If so, should that requirement be included here?

Originally posted by @bshannon in #15

Updated July 28/2021

We need to capture more about Patent Licenses (potentially both in the specification process itself and in the operations guide).

Specifically:

The working group's Steering Committee must set theselect a default Patent License policy for the specification projects that fall under the purview of the working group. The policy could be a simple statement that a particular Patent License is the default, or can be a more complex if-then-else sort of policy. Approval is by simple majority.

The working group's Steering Committee must approval all exceptions to the Patent License policy. Approval is by simple majority.

The working Group's Specification Committee must confirm, prior to initiating a ballot that will result in the establishment of a new specification, that the new specification conforms to the Patent License policy.

/cc @mmilinkov @paulbuck

The definition of Member Participant is wonky. Rather than define it in terms of having a committer on a specification project, let's define it in terms of having signed the Working Group Participation Agreement.

Service Releases, as presented in the EFSP, are considered "Bug Fix" releases. The definition of Service Release and Bug-fix are not formalized beyond a simple qualification that Service Releases contain "no significant changes or additions over the base Release". In the absence of any formal definition of what constitutes a significant change or addition, the definition is left to the Project Leadership Chain.

I believe that we can reasonable ask the PMC to assert that the sorts of changes that are acceptable in a JCP Maintenance Release are also acceptable in an EDP/EFSP Service Release.

Regarding approvals, the EFSP has this to say about Service Releases:

Service Releases (bug fixes) for a Specification Version that has
engaged in a successful Release Review do not require any further
Reviews, but must be approved by a Super-majority vote of the
Specification Committee.

How a vote is run, the materials that must be delivered to the Specification Committee in advance of a vote, timing considerations, etc. may be formalized in the implementation of the process.

The one possible oversight that I can see is that the EFSP specifically states that:

With the successful completion of a Release Review, including
approval of the Specification Committee by a Super-majority vote,
a Specification Version is Ratified and the associated artifacts
can be promoted and distributed by the Specification Committee as a
Final Specification.

This does not make allowances for Service Releases. I believe that this can be corrected by removing the reference to the Release review and going with something like this:

With the successful completion of a Release Review,
including approval of the Specification Committee by a
Super-majority vote, a Specification Version is Ratified and the
associated artifacts can be promoted and distributed by the
Specification Committee as a Final Specification.

And, perhaps, formalize that the output of a Service Release is also a Specification Version.

(Copied from Bug 543471)