27096, "lydia-duncan", "Proposal for how to handle breaking changes going forward", "2025-04-10T20:29:00Z"
opened 08:29PM - 10 Apr 25 UTC
type: Design
area: Language
In light of some recent discussions about changes to otherwise stable features (… [how to print complex numbers when one component is nan](https://github.com/chapel-lang/chapel/issues/27007), [replacing some of the Math constants with param procedures
](https://github.com/chapel-lang/chapel/issues/26571), for instance), this seemed like a good time to finish determining how to make breaking changes in a post-2.0 world.
The Chapel team at HPE has discussed some ideas internally and would like to propose a new "editions" model for handling breaking changes, similar to Rust's editions. We don't anticipate making a 3.0 any time soon, so this would enable changes that might otherwise have been blocked behind that sort of effort to get to the user base sooner, while still maintaining the stability that 2.0 has provided.
Basics
=====
Under this proposal, an edition would be a version of the language. It would be accessible using a new compilation flag, behind which breaking changes could be placed. Then, when a significant number of such changes have accumulated, the edition would be given an official name and in the following compiler release be finalized for users to rely upon, if they so choose.
As a concrete example, we've had a desire to move away from the `dmapped` keyword. Introducing a new keyword would be considered a breaking change, as users could be relying on that keyword as the name of a function or variable, for example. So we'd want to lock the new keyword behind an edition until users had been given sufficient time to transition away from using that name. In [this comment](https://github.com/chapel-lang/chapel/issues/23128#issuecomment-2073319634), we'd decided to use `over` instead of `dmapped`, so making the transition would look like this:
code using the old keyword:
```Chapel
var over = 15;
forall i in {1..n} dmapped myBlockDist { ... }
```
compilation command:
```
chpl oldCode.chpl
```
code using the new keyword:
```Chapel
var limit = 15; // `over` has been renamed to `limit` now that the new keyword is being used
forall i in {1..n} over myBlockDist { ... }
```
compilation command:
```
chpl --edition=<newEditionName> newCode.chpl
```
This would require some compiler changes to make sure that users are not penalized for new keywords that get added in future editions, but we think the benefits to users are important.
Edition Life-cycle
=============
When this concept is implemented, we would have two editions to start:
- the default edition (meant to be in keeping with Chapel 2.0 decisions)
- "pre-edition" (meant as the place to put breaking changes that aren't attached to a particular edition yet)
The pre-edition would always exist, but may have periods where it does not differ from the most recently created edition. New breaking changes would accumulate there. Likewise, there would always be a default edition, but which edition is considered the default would change as new editions accumulate.
At the beginning of a release cycle where we have a sufficient number of changes in the pre-edition, we would decide to create a new edition. The name for it would be added as an option that can be specified via the `--edition` flag, and breaking changes would become associated with that edition (though they would also still be accessible via the pre-edition). We are currently planning on having this name be the year where the edition was created, but may also give it a fun alphabetical name.
If this process goes well, that release would make the edition live for users. If we discover issues, we would remove the edition name before the release goes live and restore it at the beginning of the next release cycle, continuing to work on it and validate it until the edition is released.
When a new edition is released, we would provide a list of changes included in that edition. We're also considering providing a general flag to aid in transitioning between editions, and such a flag would be updated at this time.
Default and Old Editions
------------------------
The default edition would not change frequently under this proposal, and changing it would be on a case-by-case basis rather than a specific schedule. Old editions that are no longer the default would be dropped when the limit of the number of editions we maintain has been reached. This number has not been finalized yet but won't be immediately relevant, given how infrequently the default edition would change.
The default edition would be able to be referred to as both "default" and the name it was originally given. This would allow users to explicitly stick with a particular edition for its entire life, as well as allow other users to ensure they always rely on the default edition, even as that default shifts.
Implementation Details (developer-oriented)
=================================
We would track what features are currently in the "pre-edition". This will make it easier to document/track what to add when creating a new edition.
When tying a change to a particular edition, we would use attributes and compiler changes to indicate which edition it is associated with. The exact syntax and names for the attributes would be defined later.
Final Thoughts
===========
We think this is a strong proposal but are very interested in user feedback on the idea, as providing a good experience for users is the most important thing. There's been internal talk about moving our team meetings into an open community meeting soon and that could be a forum for talking about this issue with interested users. We can also schedule a community meeting to specifically talk about it, if there's interest. And of course, discussion on this issue itself will be important, especially if interested parties are unable to attend a meeting.
In light of some recent discussions about changes to otherwise stable features (how to print complex numbers when one component is nan , replacing some of the Math constants with param procedures , for instance), this seemed like a good time to finish determining how to make breaking changes in a post-2.0 world.
The Chapel team at HPE has discussed some ideas internally and would like to propose a new "editions" model for handling breaking changes, similar to Rust's editions. We don't anticipate making a 3.0 any time soon, so this would enable changes that might otherwise have been blocked behind that sort of effort to get to the user base sooner, while still maintaining the stability that 2.0 has provided.
Basics