Decide on an approch to versioning
Opened this issue · 1 comments
codesections commented
We need to decide on and implement an approach to versioning for _
. See the versioning section of the announcement blog post for initial thoughts/tradeoffs.
codesections commented
A few initial thoughts, all subject to change (with a tldr of "like Rakudo, but with more flexibility"):
- While
_
isv0.0.*
, no guarantees at all, including to_
's API for using sub-packages/functions. - When
_
is ready to stabilize its own API, start using calver, with the same version scheme/numbers as Rakudo (e.g.,v2022.01
) - This would not mean that all
_
sub-packages need to be ready for a stable release.- question: should unstable sub-packages go in a separate
:EXPERIMENTAL
(or maybe:PREVIEW
?) tag/namespace? - Or should they just be a
v0.x
?
- question: should unstable sub-packages go in a separate
- Plan to track Rakudo releases and release a new
_
version on each Rakudo release (~monthly) - Separately version components within
_
. Question: how?- version each sub-package? With run-time imports? Or compile-time import them all an bind an alias at runtime?
- (I'm leaning this way) version individual functions? With
multi
s (or some other dispatch solution), each candidate could match a:ver
parameter against a range of acceptable versions. (e.g., if_
were already stable,&dbg
would match onv2021.10..*
; then if a new&dbg
came out, the first might match on, sayv2021.10..v2022.02
and the second onv2022.02..*
).
- Let users supply a default version as a
use
param (note: not just by specifying the_:ver
, because that would cap the version of everything in_
).- when loading a fn (or sub-package), use that version by default, but let the user override the default by passing a
:ver
(maybe when importing the fn; for sure when calling it).:ver
should let them opt into a lower or higher version than the default. - Question: What default to use when we don't get one?
- leaning towards
$*RAKU.compiler.version.say
(upgrading Rakudo is a conscious choice) - Could do
*
(more consistent with other packages, but makes more depend on_
's version).
- leaning towards
- when loading a fn (or sub-package), use that version by default, but let the user override the default by passing a
In addition to the mechanics above, there's also the question of what _
promises to aim for. I'm leaning towards "like Rakudo" – which would mean that nothing is removed/broken (intentionally) other than on a Raku language release. (But maybe _
wouldn't require as long a period for is DEPRECATED
before removing something in the next lang release?).
- question: what about
multi
candidates that match with a higher specificity? If_
has amulti foo($a) {…}
and adds amulti foo(Int $a) {…}
, is that a breaking change? It changes the output offoo 5
. But what iffoo 5
previously threw? Is amulti foo($a)
that throws when given non-Str
arguments any different than amulti foo(Str $a) {…}
? - Given ^^^ the rule should be something like "a breaking change is one that causes an observable change in non-exceptional return values"? With some definition of "observable" that excludes certain introspection trickery (see exempt from compatibility concerns. Maybe add in some guarantee re: typed errors for exceptions users should be allowed to test against?