RFC SUMMARY
I propose that we begin tagging Hare 0.XX.Y versions, for the purpose
of improving the relative stability of the ecosystem while Hare begins
to be adopted for serious work.
The versioning scheme will be a simple date-based scheme for quarterly
releases. For instance, if a release were tagged for Q4 2023 (i.e. right
now), it would be version 0.23.3, and would be followed by 0.24.0.
If this proposal is accepted, the first release would be 0.24.0.
LANGUAGE IMPLICATIONS
The compiler will be tagged with quarterly versions. I propose that each
release must be assigned to a stable qbe release, and we set up a
separate branch which tracks qbe master to be pulled into harec master
only when qbe ships a release. If we badly want to ship some new feature
that depends on qbe changes, we can coordinate with mpu on the release
(mpu is cc'd on this email).
The specification will not be versioned until 1.0.
STANDARD LIBRARY IMPLICATIONS
Breaking API changes will have to be recorded and summarized in the
release notes each quarter. I propose adopting a convention for commit
messages (to be documented in docs/release.md) wherein a commit which
makes a breaking change will summarize that change for the release notes
and be tagged with the special trailer:
Breaking-change: 0.XX.Y
Where 0.XX.Y is the next version to be released. When preparing the
release notes, we will gather up all Breaking-change commits written
between releases and put them in the release notes, which will be
published to hare-announce.
ECOSYSTEM IMPLICATIONS
Software which aims to be stable and packaged for downstreams (e.g.
Linux distros) would presumably be well-advised to track "stable" Hare
releases. This will simplify the process of keeping Hare packages up to
date, both for the Hare toolchain and standard library and also for
downstream software which uses it.
I propose that, in order to make it easier on the ecosystem to track
releases and their breaking changes, that we cut the release a couple of
weeks before publishing it, and disseminate the release notes so that
downstreams have time to prepare changes to their code and distros need
not manage packages built against different Hare releases when updating.
EXAMPLE CODE
None
RELATED RFCS
None
[2023-12-07 10:29:02+0100] Drew DeVault:
> STANDARD LIBRARY IMPLICATIONS> > Breaking API changes will have to be recorded and summarized in the> release notes each quarter. I propose adopting a convention for commit> messages (to be documented in docs/release.md) wherein a commit which> makes a breaking change will summarize that change for the release notes> and be tagged with the special trailer:> > Breaking-change: 0.XX.Y> > Where 0.XX.Y is the next version to be released. When preparing the> release notes, we will gather up all Breaking-change commits written> between releases and put them in the release notes, which will be> published to hare-announce.
Is there a reason to include the version? It seems like the kind of thing that would backfire if a patch is to be commited at a later date, for because of depending on a yet-to-be-released version of harec/qbe, or missing the commit-window.
> ECOSYSTEM IMPLICATIONS> > Software which aims to be stable and packaged for downstreams (e.g.> Linux distros) would presumably be well-advised to track "stable" Hare> releases. This will simplify the process of keeping Hare packages up to> date, both for the Hare toolchain and standard library and also for> downstream software which uses it.> > I propose that, in order to make it easier on the ecosystem to track> releases and their breaking changes, that we cut the release a couple of> weeks before publishing it, and disseminate the release notes so that> downstreams have time to prepare changes to their code and distros need> not manage packages built against different Hare releases when updating.
I think it would be better to include the code as well so testing can be done before the actual release, this goes for both packagers and developers btw.
For example via Release Candidates, those aren't supposed to be made available to end-users, outside of maybe experimental channels a bit like git-based packages on otherwise stable packages.
On Thu Dec 7, 2023 at 4:29 AM EST, Drew DeVault wrote:
> I propose that we begin tagging Hare 0.XX.Y versions, for the purpose> of improving the relative stability of the ecosystem while Hare begins> to be adopted for serious work.>> The versioning scheme will be a simple date-based scheme for quarterly> releases. For instance, if a release were tagged for Q4 2023 (i.e. right> now), it would be version 0.23.3, and would be followed by 0.24.0.>> If this proposal is accepted, the first release would be 0.24.0.
As much as I agree versioned releases would be useful, I think we should
hold off for a little bit longer. There's quite a few relatively large
changes which are being cooked up, for example mutability overhaul,
merging hare with bootstrap harec, and hare.ini, and I'd rather wait for
those (or at least some of those) before we start tagging any releases.
Mutability overhaul in particular will break nearly every existing
codebase.
> The compiler will be tagged with quarterly versions. I propose that each> release must be assigned to a stable qbe release, and we set up a> separate branch which tracks qbe master to be pulled into harec master> only when qbe ships a release. If we badly want to ship some new feature> that depends on qbe changes, we can coordinate with mpu on the release> (mpu is cc'd on this email).>> The specification will not be versioned until 1.0.
IMO we should also have tagged releases for extended libraries as well,
to ensure that they remain up to date.
> Software which aims to be stable and packaged for downstreams (e.g.> Linux distros) would presumably be well-advised to track "stable" Hare> releases. This will simplify the process of keeping Hare packages up to> date, both for the Hare toolchain and standard library and also for> downstream software which uses it.
Providing support will be a lot trickier if some people are using an
older "stable" version and others are tracking master. Both because of
breaking changes to the language itself, but also because bug fixes will
take longer to reach those using versioned releases. At some point (once
the design of the language is more stable, and once we've addressed
common known bugs), this will be a worthwhile trade-off; I just don't
think we're quite there yet. Or, I guess, put another way: I don't
really feel comfortable with encouraging Hare to be adopted for "serious
work" yet.
A good place to start would be to more concretely prioritize certain
actionable tasks. The "priority" label on the ticket tracker is
underused; going through and finding places where it's appropriate would
be a good start.
[2023-12-07 21:42:45-0500] Sebastian:
>On Thu Dec 7, 2023 at 4:29 AM EST, Drew DeVault wrote:>> I propose that we begin tagging Hare 0.XX.Y versions, for the purpose>> of improving the relative stability of the ecosystem while Hare begins>> to be adopted for serious work.>>>> The versioning scheme will be a simple date-based scheme for quarterly>> releases. For instance, if a release were tagged for Q4 2023 (i.e. right>> now), it would be version 0.23.3, and would be followed by 0.24.0.>>>> If this proposal is accepted, the first release would be 0.24.0.>>As much as I agree versioned releases would be useful, I think we should>hold off for a little bit longer. There's quite a few relatively large>changes which are being cooked up, for example mutability overhaul,>merging hare with bootstrap harec, and hare.ini, and I'd rather wait for>those (or at least some of those) before we start tagging any releases.>Mutability overhaul in particular will break nearly every existing>codebase.
For 0.x.y in semver, breaking changes can happen at each 0.x, wouldn't that still work fine for the large changes?
I'd guess Quarterly could be too soon, so 0.$year.$month might make more sense, at least I think something a bit like Alpine's roughly monthly packaging schedule but as tags in the repository would make sense for synchronisation between distros (plus it makes it easier to refer to hare's status when addressing breaking changes).
Which could still end up Quarterly as Hare stabilizes, meaning for example 0.24.4 directly followed by 0.24.7 with no in-between releases.
>> The compiler will be tagged with quarterly versions. I propose that each>> release must be assigned to a stable qbe release, and we set up a>> separate branch which tracks qbe master to be pulled into harec master>> only when qbe ships a release. If we badly want to ship some new feature>> that depends on qbe changes, we can coordinate with mpu on the release>> (mpu is cc'd on this email).>>>> The specification will not be versioned until 1.0.>>IMO we should also have tagged releases for extended libraries as well,>to ensure that they remain up to date.
+1
>> Software which aims to be stable and packaged for downstreams (e.g.>> Linux distros) would presumably be well-advised to track "stable" Hare>> releases. This will simplify the process of keeping Hare packages up to>> date, both for the Hare toolchain and standard library and also for>> downstream software which uses it.>>Providing support will be a lot trickier if some people are using an>older "stable" version and others are tracking master. Both because of>breaking changes to the language itself, but also because bug fixes will>take longer to reach those using versioned releases. At some point (once>the design of the language is more stable, and once we've addressed>common known bugs), this will be a worthwhile trade-off; I just don't>think we're quite there yet. Or, I guess, put another way: I don't>really feel comfortable with encouraging Hare to be adopted for "serious>work" yet.
The problem of not having all the bugfixes is already pretty much there for packaged hare in distros (which is a thing, even all the way to applications, see himitsu for example) and it means software written in Hare should either track master / latest-stable in their repos, and not track earlier than latest-stable in their releases.
On Fri Dec 8, 2023 at 3:42 AM CET, Sebastian wrote:
> As much as I agree versioned releases would be useful, I think we should> hold off for a little bit longer. There's quite a few relatively large> changes which are being cooked up, for example mutability overhaul,> merging hare with bootstrap harec, and hare.ini, and I'd rather wait for> those (or at least some of those) before we start tagging any releases.> Mutability overhaul in particular will break nearly every existing> codebase.
I think that we need to start being more disciplined with breaking
changes. When the mutability overhaul comes in I am going to push for
writing a tool which rewrites your Hare code for you, at least to the
best extent possible, and I want to formalize the process in which we
dissemenate those big breaking changes into the larger ecosystem through
release notes and an announcement and suggested steps to migrate. I
think this will fit better into the release model, actually, than if we
just yolo'd it into harec master.
> IMO we should also have tagged releases for extended libraries as well,> to ensure that they remain up to date.
+1
> Providing support will be a lot trickier if some people are using an> older "stable" version and others are tracking master. Both because of> breaking changes to the language itself, but also because bug fixes will> take longer to reach those using versioned releases. At some point (once> the design of the language is more stable, and once we've addressed> common known bugs), this will be a worthwhile trade-off; I just don't> think we're quite there yet. Or, I guess, put another way: I don't> really feel comfortable with encouraging Hare to be adopted for "serious> work" yet.
Well, we'll be doing quarterly releases, so the old version will only be
"stable" for 3 months before a new set of bug fixes roll in. 3 months is
not that long, some stuff built with Hare already goes that long without
being updated to address breaking changes for instance.
On Fri Dec 8, 2023 at 5:49 PM CET, Haelwenn (lanodan) Monnier wrote:
> [2023-12-07 21:42:45-0500] Sebastian:> >On Thu Dec 7, 2023 at 4:29 AM EST, Drew DeVault wrote:> >> I propose that we begin tagging Hare 0.XX.Y versions, for the purpose> >> of improving the relative stability of the ecosystem while Hare begins> >> to be adopted for serious work.> >>> >> The versioning scheme will be a simple date-based scheme for quarterly> >> releases. For instance, if a release were tagged for Q4 2023 (i.e. right> >> now), it would be version 0.23.3, and would be followed by 0.24.0.> >>> >> If this proposal is accepted, the first release would be 0.24.0.> >> >As much as I agree versioned releases would be useful, I think we should> >hold off for a little bit longer. There's quite a few relatively large> >changes which are being cooked up, for example mutability overhaul,> >merging hare with bootstrap harec, and hare.ini, and I'd rather wait for> >those (or at least some of those) before we start tagging any releases.> >Mutability overhaul in particular will break nearly every existing> >codebase.>> For 0.x.y in semver, breaking changes can happen at each 0.x, wouldn't> that still work fine for the large changes?
I don't think semver is going to make sense for Hare and I don't intend
to use it.
> I'd guess Quarterly could be too soon, so 0.$year.$month might make> more sense, at least I think something a bit like Alpine's roughly> monthly packaging schedule but as tags in the repository would make> sense for synchronisation between distros (plus it makes it easier to> refer to hare's status when addressing breaking changes).
I do think quarterly strikes a good balance. We can always adapt if it
doesn't end up working well.
> The problem of not having all the bugfixes is already pretty much> there for packaged hare in distros (which is a thing, even all the way> to applications, see himitsu for example) and it means software> written in Hare should either track master / latest-stable in their> repos, and not track earlier than latest-stable in their releases.
+1
On Thu Dec 7, 2023 at 12:38 PM GMT, Haelwenn (lanodan) Monnier wrote:
> [2023-12-07 10:29:02+0100] Drew DeVault:> > STANDARD LIBRARY IMPLICATIONS> > > > Breaking API changes will have to be recorded and summarized in the> > release notes each quarter. I propose adopting a convention for commit> > messages (to be documented in docs/release.md) wherein a commit which> > makes a breaking change will summarize that change for the release notes> > and be tagged with the special trailer:> > > > Breaking-change: 0.XX.Y> > > > Where 0.XX.Y is the next version to be released. When preparing the> > release notes, we will gather up all Breaking-change commits written> > between releases and put them in the release notes, which will be> > published to hare-announce.>> Is there a reason to include the version? It seems like the kind of> thing that would backfire if a patch is to be commited at a later> date, for because of depending on a yet-to-be-released version of> harec/qbe, or missing the commit-window.
The appropriate thing to do would be to not apply those patches -- which
do not specify the upcoming released version -- to master. If we wanted
such a patch, we would make a v2 with the upcoming release version, and
apply that. Therefore, within any release-window, master only contains
breaking-change commits specifying the next release.
I think this RFC could be clearer on this point.
+1 for quarterly versioned releases. I think it's a good timespan.
Why not 0.YY.Q.B for bugfixes?
On Thu Dec 7, 2023 at 9:29 AM GMT, Drew DeVault wrote:
> STANDARD LIBRARY IMPLICATIONS>> Breaking API changes will have to be recorded and summarized in the> release notes each quarter. I propose adopting a convention for commit> messages (to be documented in docs/release.md) wherein a commit which> makes a breaking change will summarize that change for the release notes> and be tagged with the special trailer:>> Breaking-change: 0.XX.Y>> Where 0.XX.Y is the next version to be released. When preparing the> release notes, we will gather up all Breaking-change commits written> between releases and put them in the release notes, which will be> published to hare-announce.
It is not clearly stated in the RFC whether hare.git will be version
tagged as described for harec.git, no explicit:
> The ***standard library*** will be tagged with quarterly versions.
Along with my reply to ~lanodan, this RFC could be clearer on this point
too.
On Sun Dec 10, 2023 at 5:23 PM CET, Byron Torres wrote:
> +1 for quarterly versioned releases. I think it's a good timespan.>> Why not 0.YY.Q.B for bugfixes?
I don't think we should backport bug fixes, we should just wait until
next quarter's release and distros can backport specific patches if they
have a pressing need.