Define and Document Process for Changing Specification Version

[Pandrex247]

It came up during the development of Jakarta EE 11 that Faces created a plan for doing a 5.0 version including some breaking changes, and then wished to rein in the scope to not include the breaking changes and have the release versioned as 4.1 (to represent no breaking changes).

Approved Plan: https://github.com/jakartaee/specifications/blob/7e6077b630f692ee59f34cf13103de03c4076810/faces/5.0/_index.md Approved Plan PR: https://github.com/jakartaee/specifications/pull/620

This issue is for us to decide on and document a process for how we handle these changes, as changing the version of the specification has the following issues which need navigating:

• The specification and project page details are generated using the structure of the specifications repo.
  • This means if you simply do a PR to move the 5.0 version to 4.1 then the 5.0 pages will possibly just disappear?
• The Plan Review ballot was done against version 5.0, not 4.1.
  • Would a new Plan Review need to be done for version 4.1?
  • If we see this as a simple refinement of the plan, how do we create a paper trail to show that although the plan review was done against version 5.0 it was refined to version 4.1?
  • How do we do this in a manner that when we come to do a proper 5.0 release later down the road we don't lose this paper trail?

Solutions discussed on the spec committee call 13/12/2023 included:

• Create a PR to simply change 5.0 to 4.1
  • Possibly set up some redirects on the website so that 5.0 redirects to 4.1 (until development on 5.0 begins again proper)
• Create a PR to create a new 4.1 entry with the scope refined down, and update the existing 5.0 entry to simply be a placeholder until development on this specific version starts again proper
  • Possibly with some flavour text added to each entry to explain what happened e.g. This was originally scoped for EE 11 as 5.0 but the decision was made to change it to 4.1

[ivargrimstad]

• Create a PR to create a new 4.1 entry with the scope refined down, and update the existing 5.0 entry to simply be a placeholder until development on this specific version starts again proper

  • Possibly with some flavour text added to each entry to explain what happened e.g. This was originally scoped for EE 11 as 5.0 but the decision was made to change it to 4.1

This is the best approach, and also the approach that has been used in the past when there is ongoing work on two versions of a specification (e.g. Jakarta RESTful Web Services 3.1 and 4.0)

[Emily-Jiang]

I am a bit confused with this issue. This issue sounds like further discussion needed. Actually, at this week's Jakarta Specification call, we have concluded with the following:

• Request that the 5.0 entry on the Jakarta Faces specification page be updated to insert at the top the revised content for EE 11 and note that the release designation is now 4.1. The original content of the page that was present at Plan Review remains as it was. 
• Request that in the Release Review for Jakarta Faces 4.1 a note also be added to explain (bridge) to the original Plan Review which was designated 5.0 for a record of this change. 
• Use a client side redirect to make it so https://jakarta.ee/specifications/faces/5.0/ redirects to https://jakarta.ee/specifications/faces/4.1/
• No ballot is required. 

[Pandrex247]

Sorry yes I missed the context in the description that we decided something in that spec call.

This issue is to codify what we already agreed in writing so that we know what to do next time this topic gets brought up, potentially continuing the discussion if required since attendance at that call was quite sparse.

[Emily-Jiang]

Sorry yes I missed the context in the description that we decided something in that spec call.

This issue is to codify what we already agreed in writing so that we know what to do next time this topic gets brought up, potentially continuing the discussion if required since attendance at that call was quite sparse.

I thought we agreed to create an issue to document what we have agreed on the call for future reference. We might have different understandings.

[Emily-Jiang]

• Create a PR to create a new 4.1 entry with the scope refined down, and update the existing 5.0 entry to simply be a placeholder until development on this specific version starts again proper

  • Possibly with some flavour text added to each entry to explain what happened e.g. This was originally scoped for EE 11 as 5.0 but the decision was made to change it to 4.1

This is the best approach, and also the approach that has been used in the past when there is ongoing work on two versions of a specification (e.g. Jakarta RESTful Web Services 3.1 and 4.0)

We discussed at a great length with Wayne. The above approach will push the problem down the road. When Faces decides to do 5.0, they have to remove most of the current Plan reviews documented in 5.0 and start all over again. At the same time, there are two in progress items, which might cause confusion. Wayne advised us not to make things too complicated for no appropriate reason. Besides, the plan is allowed to be updated. If we directly change the scope of the current plan, it reflects the reality. Besides, no ballet is needed for the scope changes.

[paulbuck]

Suggestion to add a sentence to the Creating a Release Plan in the Jakarta EE Spec Operations document https://jakarta.ee/committees/specification/operations/ to note how to document changes to release designations.