Process for retiring a Specification?

[kwsutter]

I don't see where our EFSP process outlines the proper mechanism to retire a Specification. We have a situation in Jakarta EE where a standalone Specification is planned to be merged into another Specification. What is the proper means of closing off or retiring the current Specification? Do we need a "Retirement Review"?

[waynebeaton]

A specification project would be retired using a termination review per the EDP. A specification project that supports multiple specifications that intends to persist after dropping one of the specifications, can just drop the specification (after socializing the retirement with the community). I initially thought that dropping a specification might be a plan item in a plan review, but I don't see the value in running a plan review exclusively to say that you're dropping a specification (a corresponding release review that just removes a specification makes no sense to me).

In either case, I would expect that the corresponding repository(ies) be marked as archived but kept around for posterity.

What do we do with previous Final Specifications? That, I believe, is entirely up to the working group. Existing versions of the specification could be kept around or retired. Again, I believe that socialization with the community is the important part.

Whatever the case, I believe it a best practice to involve the specification committee in the decision making process. If the specification committee disagree, then they have an opportunity to find resources to take over support of the specification or find a new home for it.

[waynebeaton]

So, I'm thinking that there's really no practical change in the process (i.e., I think that we can get a long with what we already know), but including a little something about terminating a specification or specification project would be a helpful addition to EFSP.

[kwsutter]

Good points, Wayne. I think we have two cases here to consider...

1. Retiring a Specification Project. This can be covered by the EDP processes.
2. Retiring a Specification document. Basically, just quit working on it. Updating the README or something to indicate the current state of the Specification would probably be good.

I think you're right. Maybe I was just thinking too much on this topic. The specific case that is bringing this up is that Jakarta Web Services Metadata wishes to get merged into Jakarta XML Web Services. These are in the same Specification Project, so we're not retiring the whole Project. We could update the README for the Metadata repository to indicate it's getting merged into the other Specification. And, once that Release Review is complete, then we could archive that repository for safe keeping.

(I wonder if we should be doing the same type of archiving with those other Specification repositories in the Stable Project that were removed in Jakarta EE 9? Is archiving permanent? Or, can it be unarchived if it would need to be updated sometime down the road?)

[waynebeaton]

2. Retiring a Specification document. Basically, just quit working on it. Updating the README or something to indicate the current state of the Specification would probably be good.

I tend to think of this in the same manner as I do for functionality retired from a software project: like you said, just quit working on it. There's a best practice of deprecating functionality/APIs before removing functionality outright, but there is no specific requirement in the process to do so.

The removal functionality/content is something that should be captured in a release plan, change log, and release documentation.

(I wonder if we should be doing the same type of archiving with those other Specification repositories in the Stable Project that were removed in Jakarta EE 9? Is archiving permanent? Or, can it be unarchived if it would need to be updated sometime down the road?)

We have some options here, and what we pick really depends on the circumstances.

• We can just decide that a repository is archived, but leave it in an active state just in case somebody needs to open an issue;
• We can mark a repository as archived on GitHub (and GitLab, I believe) which I believe prevents anybody from opening issues or otherwise doing anything more than cloning the repository; or
• We can delete the repository.

There's probably another case (or two)... what do we do when multiple specifications are hosted in the same repository (I believe that OSGi does this)? Just delete the content, or somehow mark the directory as archived (e.g., subdirectory README).

Strictly speaking, if we delete the repository, the IP Policy would demand that we engage in an IP review (that would go quickly) to bring it back. If a repository is just marked as archived, then bringing it back would require just changing the state.

My strong preference tends to be to mark the repository as archived. I don't think that the EFSP is the right place to capture these options. Perhaps they belong in the operations guide (maybe as an FAQ entry).

I do, however, think that we should include a some content regarding termination in the EFSP.

Terminating a specification project is the same as terminating a project per the EDP. The EDP, however, characterises a Termination Review as an opportunity to find a new development team to keep "the Project active".

The purpose of a Termination Review is to provide a final opportunity for the Committers and/or Eclipse Membership at Large to discuss the proposed archiving of a Project. The desired outcome is to find sufficient evidence of renewed interest and resources in keeping the Project active.

I don't think that this is necessarily a showstopper, but do wonder what this might mean in terms of intellectual property grants.

A termination review is not included as a "Check Point Review" in the IP Policy. So no specification committee ballot is required, and no intellectual property grants are locked in by engaging in a termination review.

I expect that this would not happen in practice, but... if we had a Termination Review fail (that is, we decide not to terminate and a new team steps up), we would only have necessary intellectual property grants on everything leading up to the last release/progress review. If any new content was introduced during the period following that last release/progress review, then we'd either need to engage in a progress review, or throw out the new content. I believe that all of this flows out of the process and so does not need to be added; we might consider adding it to the operations guide.

Terminating a specification is, IMHO, just a plan item followed by archival/removal of the content from the project. If a specification project would wind up in a state where it had no specifications, then that specification project would, I believe, have to be terminated.