Be inclusive of process specifications

The EFSP was designed specifically to deal with technical specifications that include technical things like APIs and TCKs. While it avoids specifically defining technical artifacts and I believe that it possible to interpret the EFSP to make those things optional, it's very evident that technical specifications are first class.

Let's see what we can do to make it treat process specifications as first class things.

Update (April 5 2024) :

I've created a draft and a diff:

• Eclipse Foundation Specification Process 1.4 (DRAFT)
• Differences between version 1.3.2 and 1.4 (DRAFT)

I've also created a presentation that walks through the differences:

• 2024-04_EFSP_1.4_DRAFT_for_Specification_Committee_Review.pdf

We need to define Process Specification.

I believe that this can be as simple as "A specification that defines a process".

Based on some quick searches, others use definitions along these lines (paraphrased): "A description of the steps involved in a process, along with the inputs and outputs for each step." This is too specific for our purposes, as a process specification could potentially be as simple as a checklist.

We may also require a more general definition of Specification. Perhaps something like this: "A Specification is a [detailed] description of how something should be done, made, or designed." A Process Specification, then, is "a description of how something should be done".

Does this, then, necessitate defining a Technical Specification?

I've added/modified the following definitions in the draft.

Specification :

A Specification is a description of how something is done, made, or designed. See Process Specification and Technical Specification.

Process Specification :

A Process Specification describes how a process is put into practice. See Specification.

Technical Specification :

A collection of Application Programming Interface (API) definitions, descriptions of semantic behaviour, data formats, protocols, and/or other referenced specifications, along with its TCK. See Specification

The Patent License for a Process Specification is always the Implementation Patent License.

The existing statement that "All Specifications produced by a Specification Project must use the same Patent License." means that a hypothetical Specification Project that produces both Technical and Process Specifications would be compelled to use the Implementation Patent License for Technical Specifications. The work around is to create separate projects (which I expect will be the norm anyway). This may be an example of thinking about this too hard.

The notion of Compatible Implementation makes no sense for a Process Specification.

Likewise, it not generally sensible to talk about a TCK for a Process Specification. Is a TCK ever meaningful for a Process Specification?

It's not clear whether or not a TCK is ever meaningful for a process specification, so let's not add any language that prevents it.

Compatible Implementation :

Any implementation of a Technical Specification that fulfils all requirements of a Final Specification as demonstrated by fulfilling all requirements of the associated TCK. The notion of a Compatible Implementation is not meaningful for a Process Specification.

Technology Compatibility Kit (TCK) :

Software and/or documented requirements that support the testing of implementations to ensure that they are compatible with the Technical Specification. A TCK is not generally meaningful for a Process Specification.

It may be worth reconsidering the the statement that a TCK is note generally meaningful for a Process Specification. It's not clear that this adds any value (it doesn't say either way whether or not a process specification can have a TCK).

Are Milestone Builds meaningful in the context of a Progress Review?

A build is just, basically, turning an AsciiDoc file into a PDF.

I'm inclined to just remove the notion of Milestone Build from the EFSP and lean on the definition in the EDP. The main difference is that the EFSP requires that milestone builds be created for specific reviews. This feels like an implementation detail at best. At worst, it may be a blocker in the event that there is some technical limitation that prevents a specification team from creating a required milestone build for a progress review.

The notion of a milestone build with regard to specifications is, IMHO, an implementation detail. The nature of a milestone build and the requirements placed upon it are working group-specific, so it makes sense (to me) to leave this as a detail for the working group to decide.

Milestone build is already defined in the EDP. Redefining it here adds no value.

The Milestone Build definition is removed, and the definition of Release Candidate changes.

**Release Candidate : **

A feature-complete build Milestone Build.

The requirement to describe milestone builds is removed from plan requirements, but we retain the requirement to list tentative dates for reviews. I'm fairly confident that this actually reflects current practices.

A Release Plan lists themes and, areas of focus, describes Milestone Builds, and lists tentative dates for Reviews.

Whether or not a milestone build is required for a progress review seems very situational. It could be, for example, that a progress review is called because the project team is unable to produce a milestone build.

To extend the Release Cycle, the Project Team must stage a Milestone Build and engage in a Progress Review.

mentioned in commit fbba4c43

changed the description

Remove the definition of "Brand".

This definition is not used specifically in the context of implementing the specification process. It’s not used in any of our governing documents.

I'm confident that this is just housekeeping and should have no practical impact.

Change the nature of Specification.

This is a big one. A process specification does not have the same artifacts as a technical specification. We expect, for example, that a process specification does not (in the general case) have a TCK. Nor does it generally make sense to talk about a process specification have a compatible implementation.

The sorts of artifacts that we had previously associated with a Specification are now associated with a Technical Specification.

I believe that this is backwards compatible, but would value the assessment of others. Along with this change, the notion of Specification becomes abstract. I believe that we can still reasonably talk about specifications when we mean technical specifications as the context should establish meaning.

Specification :: A Specification is a description of how something is done, 
made, or designed. See Process Specification and Technical Specification.

Technical Specification :: A collection of Application Programming Interface 
(API) definitions, descriptions of semantic behaviour, data formats, protocols, 
and/or other referenced specifications, along with its TCK. See Specification

Process Specification :: A Process Specification describes how a process is 
put into practice. See Specification.

We might consider representing this visually with a UML image:

@startuml
abstract class Specification as "Specification" {
{field}+document
}

class SpecificationDocument as "Specification\nDocument" {
{field}+Copyright (Eclipse Foundation)
{field}+Licence (EFSL)
{field}+Content
}

class ProcessSpecification as "Process\nSpecification" extends Specification {
}

class TechnicalSpecification as "Technical\nSpecification" extends Specification {
{field}+compatibleImplementation
{field}+api
{field}+tck
}

class CompatibleImplementation as "Compatible\nImplementation" {
}

Specification::document *-- SpecificationDocument
TechnicalSpecification::tck o-- "1" TCK
TechnicalSpecification::compatibleImplementation o-- "1..n" CompatibleImplementation
TechnicalSpecification::api *-- "0..1" API
@enduml

We don't require Ratified to be a defined term. It just adds noise.

The term is unnecessary. It does not appear in any governance documents.

The Project Team must engage in a successful Release Review before the final Specification Version may be ratifiedRatified, after which theA Specification Version becomes a Final Specification when it is Ratified.

Its use is potentially confusing:

All Specification Versions referenced by a Ratified Final Specification must themselves be Final SpecificationsRatified.

Ratification as a concept still exists, but is just not a defined term

The Eclipse Foundation Specification License 1.1 contains elements that make it specific to software implementations of technical specifications. To accommodate process specifications an update is required. We're working on this update separately.

At this point in time, we believe that the EFSL 1.1 will continue to be viable for technical specifications and so we will not compel projects to update to the new version (which we're currently naming 2.0).

We're making this explicit in the EFSL 1.4 draft:

The Specification Document for the Final Specification must be distributed as read-only text under the Eclipse Foundation Specification License. A Technical Specification can use either version 1.1 or 2.0. A Process Specification must use version 2.0.

changed the description

The Eclipse Board of Directors reviewed a draft during their April meeting and had comments regarding this deletion:

Each Specification Version references specific versions of its constituent artifacts (if any). 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.

They stated that they "felt this weakens the definition unnecessarily. The suggestion was to instead of delete this text, preface it with "For Technical Specifications, these artefacts include ..."

I believe that the rest of the document supports this requirement, but it's not wrong to reinforce it.

I've restored the statement, but with some changes in structure and a qualification that it applies specifically to Technical Specifications.

Each Specification Version references specific versions of its constituent 
artifacts (if any).

For a Technical Specification, constituent 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.

I've also removed the conceptual structure image from the draft, as I don't believe that it adds value. This diagram, or something similar to it will persist in the operations guide in relation to technical specifications.

@wbeaton removing the diagrams such as for the “Conceptual structure of a Specification Version” and “Conceptual model of the transition from a Specification Version to a Final Specification” in my view leaves the implementers of the Specification Process missing some vital visual aids to help understand the process. I think if possible to do a version of the diagram for Process Specifications and Technical Specifications separately, it would help users to see the main differences between them, like that the TCK and compatible implementation(s) are not required for Process Specifications.

mentioned in commit 54ba5654