Luke Boswell (Aug 29 2024 at 06:54): Luke Boswell (Aug 29 2024 at 06:54):Ok, I've written this up into a proposal... I've tried to faithfully capture everything above.
Gist: Proposal for Release Management
Notification Bot (Aug 29 2024 at 06:54):A message was moved here from #ideas > Monorepo? by Luke Boswell.
Luke Boswell (Aug 30 2024 at 03:20):Looking for any feedback - or even an emoji :thumbs_up: or :thumbs_down:
@Anton will likely have the veto here, but trying to consolidate our discussion into a single resource.
Sam Mohr (Aug 30 2024 at 03:30):Reading now!
Brendan Hansknecht (Aug 30 2024 at 03:50):I'm sure the devil will be in the details, but I am +1 overall
Sam Mohr (Aug 30 2024 at 04:04):Would we maybe want to support roc-json? I know it's not owned by the roc repository, but it's pretty important
Sam Mohr (Aug 30 2024 at 04:05):Also, if it's possible to do automatic builds every week, that would be much better than requiring a manual build
Sam Mohr (Aug 30 2024 at 04:06):Even biweekly would be fine for manual builds, but weekly is a lot of busy work IMO
Brendan Hansknecht (Aug 30 2024 at 04:21):i think it would be best if we do automatic promotion every week if all of the core platforms and packages work with the prerelease
Brendan Hansknecht (Aug 30 2024 at 04:22):So by default it is no work
Brendan Hansknecht (Aug 30 2024 at 04:22):If something breaks, it can alert us
Brendan Hansknecht (Aug 30 2024 at 04:22):We can either do a quick bug fix if it is just a bug or increment the breaking version number cause we missed something
Brendan Hansknecht (Aug 30 2024 at 04:22):I think this should be reasonable to automate
Brendan Hansknecht (Aug 30 2024 at 04:23):Just roc test on a number of trusted packages along with the tests for basic cli and basic webserver.
Luke Boswell (Aug 30 2024 at 07:15):If we decide to go this direction, and we want to remove the basic-cli cli tests, I would like to do that in my rebuild-host PR. It's touched all of those tests already, and I need to get in and do a merge to update everything again if builtin Task lands, and so if we are removing them then this will be so much easier to merge and prepare it for review.
Luke Boswell (Aug 30 2024 at 07:16):Or I guess we could do it in a separate PR, merge that, and then I merge main...
Sam Mohr (Aug 30 2024 at 07:16):Where would the basic-cli tests currently in roc-lang/roc go?
Luke Boswell (Aug 30 2024 at 07:18):Well I think most of them are already in roc-lang/examples.
Luke Boswell (Aug 30 2024 at 07:18):Yeah, they're already covered over there
Luke Boswell (Aug 30 2024 at 07:20):Except the combine-tasks.roc example you recently added Sam. That should probably be moved across to the effects zig test platform -- also makes sense to do that in my build-host PR.
Sam Mohr (Aug 30 2024 at 07:29):Great, code clean up is always nice
Anton (Aug 30 2024 at 13:52):Thanks @Luke Boswell, this looks pretty good :)
Anton (Aug 30 2024 at 13:52):Just for:
Daily
A CI job that tests all-the-things.
Uses the latest available pre-release for roc and platforms.
If the pre-release only changes weekly, there is no need for daily testing right?
Anton (Aug 30 2024 at 13:53):0.0.0-alpha.12+479feca looks quite hairy and unconventional.
Anton (Aug 30 2024 at 13:53):Inluding both 0.0.0 and alpha would be redundant in my opinion
Anton (Aug 30 2024 at 13:54):I would prefer alpha-12+479feca
Richard Feldman (Aug 30 2024 at 15:20):can we call it like build instead of alpha?
Richard Feldman (Aug 30 2024 at 15:20):I know the modern definitions are muddied, but to me, "alpha" has always meant "internal only testing release" and "beta" has always meant "public testing release"
Richard Feldman (Aug 30 2024 at 15:21):whereas this is just "here's a particular build of this commit, we're not setting any expectations about the intended audience or the quality level whatsoever"
Brendan Hansknecht (Aug 30 2024 at 17:08):I think the name is all about user expectation:
0.0.0-alpha.12+abc probably too strong a signal
alpha.12+abc I think this is the right level
build.12+abc I think people will consider this a real release and judge it more
Brendan Hansknecht (Aug 30 2024 at 17:09):"we're not even a version 0.0.0"
"What do you mean your system says version 12"
Brendan Hansknecht (Aug 30 2024 at 17:10):"actually it's breaking change number 12"
"Oh ................."
Richard Feldman (Aug 30 2024 at 19:20):what about 0.0.0-build-12+abc?
Sam Mohr (Aug 30 2024 at 19:46):Richard Feldman said:
what about
0.0.0-build-12+abc?
According to https://semver.org/, the prerelease field (a.k.a. "build-12") is supposed to be dot-separated
Sam Mohr (Aug 30 2024 at 19:47):But otherwise, that works for me
Richard Feldman (Aug 30 2024 at 20:10):I wonder if we could derive the build number (or maybe call it the commit number?) from the commit
Richard Feldman (Aug 30 2024 at 20:10):e.g. if it's the 12345th commit in the repo, call it 0.0.0-commit-12345+abc
Richard Feldman (Aug 30 2024 at 20:11):because that way it's monotonically increasing (so we can easily tell which ones are newer than the previous ones) but also the implication is that all you should need is that commit, and we don't do multiple builds of the same commit using different information outside the commit
Sam Mohr (Aug 30 2024 at 20:14):You know what, that works. I don't think "which breaking version, specifically, are we on?" is important to communicate
Sam Mohr (Aug 30 2024 at 20:14):And it's deterministic, automatable, and human-readable
Brendan Hansknecht (Aug 30 2024 at 21:35):That doesn't work
Brendan Hansknecht (Aug 30 2024 at 21:35):We want people to be able to upgrade without question if there are no breaking changes
Brendan Hansknecht (Aug 30 2024 at 21:35):So i think it is really important to have a breaking change number
Brendan Hansknecht (Aug 30 2024 at 21:36):That enables platforms to depend on roughly 0.0.0-build-12+*
Brendan Hansknecht (Aug 30 2024 at 21:36):I think this is a super important property for maintenance of this system
Richard Feldman (Aug 30 2024 at 22:05):Brendan Hansknecht said:
We want people to be able to upgrade without question if there are no breaking changes
I think if we want this then we should ship an 0.1 and then do semver
Brendan Hansknecht (Aug 30 2024 at 22:14):I mean i think that is essentially the feature we want. It is really what we need to decouple platforms from the main roc repo head version.
Brendan Hansknecht (Aug 30 2024 at 22:15):I think we just are less confident about giving this a true semver for 2 reasons:
Brendan Hansknecht (Aug 30 2024 at 22:15):But I think for this decoupling, it is quite important that all platforms attempt to use the latest minor version.
Brendan Hansknecht (Aug 30 2024 at 22:15):Cause we still need that feedback to catch regressions and keep roc functional
Sam Mohr (Aug 30 2024 at 22:16):So maybe 0.1.<breaking-patch>-alpha.<next int OR commit number>+<commit hash>?
Brendan Hansknecht (Aug 30 2024 at 22:16):Basically, this is live at head but with a little bit of delay and a grace period for breaking versions to decouple work.
Sam Mohr (Aug 30 2024 at 22:17):Or maybe just 0.1.<breaking-patch>-alpha+<commit hash>
Brendan Hansknecht (Aug 30 2024 at 22:17):To be fair, this could be dealt with without versioning
Brendan Hansknecht (Aug 30 2024 at 22:18):It could just be recommended and nightly releases.
Brendan Hansknecht (Aug 30 2024 at 22:18):Recommended is updated when all core platforms/packages work with nightly
Brendan Hansknecht (Aug 30 2024 at 22:18):So by default, recommended would also update nightly
Brendan Hansknecht (Aug 30 2024 at 22:18):On breaking changes, there would be a longer lag time
Brendan Hansknecht (Aug 30 2024 at 22:19):But I do think that is the core of the decoupling we are trying to facilitate.
Sam Mohr (Aug 30 2024 at 22:19):I know the worry with introducing any non-zero semver is you get a Hollow Knight: Silksong situation. Just implying that there will be a release sometime will make people upset if it doesn't happen in a year or two
Brendan Hansknecht (Aug 30 2024 at 22:20):Yeah, and 0.1.0 is practically seen as production ready nowadays. Definitely by 0.10.0 or so.
Sam Mohr (Aug 30 2024 at 22:20):So if this is really about setting expectations as well as making a weak contract between Roc, its platforms, and app authors, then we should probably avoid even 0.1
Sam Mohr (Aug 30 2024 at 22:20):Yeah, unironically
Sam Mohr (Aug 30 2024 at 22:20):Not that it should be, but it's the world we live in
Sam Mohr (Aug 30 2024 at 22:21):I think 0.0.X would be fine for communicating a "we aren't even thinking about releasing anything soon"
Brendan Hansknecht (Aug 30 2024 at 22:23):I'd be happy with that. Though we do need two numbers. 0.0.X+<commit-hash> cause X is only incremented on breaking changes. If no breaking changes, commit hash just keeps going up.
Brendan Hansknecht (Aug 30 2024 at 22:23):Or well, keeps changing.
Brendan Hansknecht (Aug 30 2024 at 22:23):Cause commit hash is random
Sam Mohr (Aug 30 2024 at 22:24):So... 0.0.<breaking-version>-alpha+<commit-hash>? I'm okay with or without the alpha prerelease segment
Luke Boswell (Aug 30 2024 at 22:27):I think 0.0.X+<commit-hash> would work. :plus:
Luke Boswell (Aug 30 2024 at 22:47):Anton said:
I would prefer
alpha-12+479feca
I also think this could work, but I prefer the one above because it's still just semver.
So when we do decide it's time for a minor numbered release we just increment one number. So from 0.0.<breaking>+<commit-hash> to 0.<minor>.<patch>+<commit-hash>
Brendan Hansknecht (Aug 31 2024 at 02:08):I don't follow this last comment with 0.<minor>.<patch>+<commit-hash>...
Oh, do you mean when we decide to make the jump to 0.1.0?
Luke Boswell (Aug 31 2024 at 02:10):Yeah, eventually we will want to have a numbered release and provide some kind of stability guarantee. Like, you can use 0.xand we will backport any serious bug fixes, but you can sit on that until the next 0.x release. (I assume -- I haven't done this kind of release management before)
Luke Boswell (Aug 31 2024 at 02:10):Maybe by then it would be better to go to a 1.minor.patch but that sounds like a long way away.
Brendan Hansknecht (Aug 31 2024 at 21:28):yup
Luke Boswell (Oct 24 2024 at 01:05):I'm getting excited that the rebuild host PR is almost ready to land... in preparation I've updated the above process. Looking for endorsement or concerns. I'd like to make an Issue for this so we can start thinking about the work we need to do to implement.
This proposal aims to provide improved stability for Roc users while enabling compiler development to progress without being blocked by the need to fix all known issues in dependent platforms and packages.
While Roc is early in its development with many known breaking changes ahead, user feedback is crucial for validating design assumptions. This process outlines a methodology to enable validation during the development of the compiler, language, and broader ecosystem.
The core concept is that Roc maintains a recommended nightly version, updated when "supported" packages and platforms are working correctly with the latest nightly build. When the Roc main branch receives a breaking change, supported platforms (like basic-cli and basic-webserver) can be updated subsequently.
The recommended nightly is then updated once all components are working together harmoniously, including website examples.
New roc version format: 0.0.<breaking>+<commit-hash> e.g. 0.0.12+479feca
<breaking>: An incrementing number stored in the repository, increased only when breaking changes are introduced.<commit>: The hash of the latest commit in the version.Build pre-releases:
New platform releases should use the newest Roc pre-release
If fixes are required:
A daily CI job tests the entire ecosystem:
roc-lang/examples (hosted on the website)roc-lang/basic-cliroc-lang/basic-webserverlukewilliamboswell/basic-ssg (used to generate the website)roc-lang/unicoderoc-lang/path (WIP)lukewilliamboswell/roc-jsonlukewilliamboswell/roc-parserNote: CI jobs may fail when platforms haven't been upgraded due to breaking changes or bugs. These issues are tracked and linked in the release tracking issue to facilitate coordination.
roc-lang/rocNon-breaking changes
- Target roc-lang/roc/tree/main branch
- No change to <breaking> version
Breaking changes
- Target roc-lang/roc/tree/main branch
- Must increment the <breaking> version
Sam Mohr (Oct 24 2024 at 07:18):The plan looks good to me! I'm wondering if we might consider moving important crates to the roc-lang organization, like roc-json. It implies a greater level of stability, like packages in the rust-lang-nursery. It does lose the benefit of us figuring out migration for packages outside of the main org.
Sam Mohr (Oct 24 2024 at 07:18):(deleted)
Luke Boswell (Oct 24 2024 at 07:22):I'm hoping someone writes a fast json package. :sweat_smile:
Luke Boswell (Oct 24 2024 at 07:30):My concern with adding more supported packages is just our limited resources. It's already a lot to coordinate when we have a big breaking change, and if we add more things like json and parser etc in then we will feel pressure to do those as well. OTOH they're also super easy to maintain and usually I can do it in a couple hours for all these packages. Similar to elm, there just doesn't seem to be many things that mean they have to be upgraded.
Brendan Hansknecht (Oct 24 2024 at 15:34):I don't quite follow the weekly tasks and how this all fits together.
My assumption was that the daily CI job would post a new recommended nightly whenever it passes. If it fails, we would have to manually intervene to update the breaking change number and each individual platform. Once all platforms are updated, the CI job will pass again and update the recommended version to the version with the incremented breaking change number.
Brendan Hansknecht (Oct 24 2024 at 15:35):So by default, no one touches any of this and CI just runs by itself. There would be no weekly work. Just work each time the CI job fails due to a new breaking change entering the pipeline.
jan kili (Nov 21 2024 at 22:53):Should we cut v0.1.0 this week for the sake of AoC newcomer UX?
jan kili (Nov 21 2024 at 22:54):My motivation: https://roc.zulipchat.com/#narrow/channel/316715-contributing/topic/Help.20upgrade.2Ftest.20purity.20inference/near/483803483
Luke Boswell (Nov 21 2024 at 22:54):Well it would be 0.0.1+479feca and not until Monday next week I think ... but yeah I would like to. :smiley:
jan kili (Nov 22 2024 at 17:03)::loudspeaker: Bumping for consensus :interrobang:
Anton (Nov 22 2024 at 17:33):We'll see if there is time, I would like to finish PR#6921 first and I've got a couple of other things I need to do before I can get to that PR.
jan kili (Nov 23 2024 at 21:02):Assuming we start doing non-nightly perma-releases next week, how about we name one of them v0.0.1-2024aoc1?
Anton (Nov 25 2024 at 09:53):That feels a little weird to me, it would make me wonder if this version contains special changes for aoc; "If I'm not using roc for aoc, does that mean I should get a different version?". The commit short sha feels self-evident, at least for those familiar with git.
Luke Boswell (Jan 06 2025 at 04:28):Ok, new Proposal for Release Management v3 .
I've updated this based on all of our discussion. Please let me know if you have any serious concerns.
Sam Mohr (Jan 06 2025 at 04:30):This looks really good to me!
Sam Mohr (Jan 06 2025 at 04:31):When would we want to start implementing this? After snake_case, PNC, and Task removal?
Luke Boswell (Jan 06 2025 at 04:32):Today I hope
Luke Boswell (Jan 06 2025 at 04:35):I'm not sure if we need a new build... maybe we can just rename the current one? But it would be helpful to land the breaking changes from that other thread.
Luke Boswell (Jan 06 2025 at 04:36):Im not sure on our status with th PI upgrades etc. We wanted to update the examples and exercism etc.
Anton (Jan 06 2025 at 10:37):Examples are 97% done: https://github.com/search?q=repo%3Aroc-lang%2Fexamples%20Task&type=code
Anton (Jan 06 2025 at 10:38):Exercism is done too https://github.com/exercism/roc/pull/171
Anton (Jan 06 2025 at 14:39):The proposal looks good @Luke Boswell!
Anton (Jan 06 2025 at 14:40):Maybe we should go with 0.0.0 as in 0.0.0-alpha<breaking>+<commit> instead of 0.1.0-alpha<breaking>+<commit>, to not give the impression that a 0.1.0 release is immenent?
Anton (Jan 06 2025 at 14:41):Would we still do nightly releases as well, or just update the commit sha on a near daily basis?
Brendan Hansknecht (Jan 06 2025 at 15:12):I think updating the sha replaces nighties. It is versioned roc.
Brendan Hansknecht (Jan 06 2025 at 15:13):Just with potentially delayed updating of the recommended version.
Brendan Hansknecht (Jan 06 2025 at 16:27):Minor proposal change (clarification?), lets make our github releases be for 0.0.0-alpha<breaking>-*.
This will avoid bloating our releases with tons and tons of versions.
Instead, it is one rolling release for each breaking change group.
Brendan Hansknecht (Jan 06 2025 at 16:28):This is really just about what appears as github headers. Avoids making a release header for every single nightly run.
Anton (Jan 06 2025 at 16:31):Nice, didn't know about that
Brendan Hansknecht (Jan 06 2025 at 16:54):I was debating just trying to implement this outside the roc repo (for testing,
but I thought it would be more valuable to first just write out my thoughts.
This is an expansion on the proposal above to attempt to get concrete on what the github action flow would look like.
Currently alpha12-abc is released.
Roc breaking change number is still 12 as well.
As such, on the roc github releases page there is version alpha12-*.
It is the latest release.
In nightly job, build and test all core platforms with the newest commit to roc.
Also runs all roc repo tests to avoid bugs that sneak into main.
If it passes, replace the binaries in alpha12-* with the newer roc binaries.
So yesterday, alpha12-* had binaries for alpha12-abc, but after a successful job it would have binaries for alpha12-def.
If any tests fail, fail the job, noting that the breaking change number likely needs to be incremented.
If the failure was a flake or a temporary bug, we just leave everything alone.
The next nightly build will grab the bug fixes and successfully update alpha12-*
If the failure was a missed breaking change, we update the breaking change number.
Note, we should increment this number preemptively if we know something is a breaking change.
In some cases, due to breaking changes, roc will move ahead of the core platforms.
For this example, we will say that the platforms are still using alpha12-*, but roc is on alpha13-*
In this setup, we don't get as much testing, but that is ok, alpha13-* is a pre-release and not the recommended release.
To begin with, no platforms even have pre-releases for alpha13-*.
As such, the nightly job for alpha13-* will only be testing the roc repo.
It will be best effort to increment the breaking change number to 14 when a breaking change comes in.
That said, at this stage, with no platform have pre-releases even, it is more likely to accidentally be missed.
As platforms get pre-released, we will add the pre-release url to the nightly job (not sure if this can be automatic, but a small PR after core platform pre-release would be fine).
The job will pass and fail the same way as the base release flow, just with less platforms.
Once all core platforms have a prerelease that is passing with on alpha13-*, we will manually trigger a promotion actions to promote alpha13-* to the latest release and promote all platform pre-releases as well.
This step is manually triggered (we also would make sure any docs are updated as needed before triggering this).
This will do one final check using the published binaries in alpha13-* against the pre-releases to make sure everything is good.
Note: I assume this job may start as manual work before we iron things out.
The recommend release may fall multiple breaking change versions behind the latest pre-release. Recommended alpha12-*. Platform pre-releases alpha13-*. Current roc main alpha14-*. This is fine. This is part of the reason why promotion is manually triggered. We likely will next trigger a promotion to alpha13-* even though alpha14-* is already pre-released.
Anton (Jan 06 2025 at 17:15):Looks good!
Anton (Jan 06 2025 at 17:20):One issue that I'm not sure how we can get around:
The reason that there is a manual step to the nightly process right now is because our GITHUB_TOKEN can be compromised. This is because we use self-hosted CI runners. The GITHUB_TOKEN is now set to read only.
Anton (Jan 06 2025 at 17:21):Automatically uploading releases would need (at least limited) write access for CI.
Brendan Hansknecht (Jan 06 2025 at 17:22):If we need to make it just do the tests and separately have someone run a script to actually push the update, that is ok...just not as nice
Anton (Jan 29 2025 at 10:49):I'd like to keep the current (old) nightly available and was thinking about publishing that one as 0.0.0-alpha1-* and then current TESTING as 0.0.0-alpha2-*, while also turning current nightly-TESTING into nightly-latest. So an incremental change to the new release management without any automation for now. Thoughts?
Luke Boswell (Jan 29 2025 at 10:56):Are you thinking of throwing away releases? I thought the idea was that platforms can upgrade at their own pace. So if there's an issue with a release, we just bump the breaking number and make another.
Luke Boswell (Jan 29 2025 at 10:57):If we throw the releases away then that breaks anyone uses an older version. Or is it just we keep one release per breaking number?
Anthony Bullard (Jan 29 2025 at 10:57):One thing I really wish is that roc-lang owned platforms had their versions somehow harmonized with the compiler version they are compatible with
Anton (Jan 29 2025 at 11:00):Are you thinking of throwing away releases?
No I want to do the opposite :big_smile: , make the old nightly available under 0.0.0-alpha1-* and the new one under 0.0.0-alpha2-* and keep those around forever
Anton (Jan 29 2025 at 11:02):One thing I really wish is that roc-lang owned platforms had their versions somehow harmonized with the compiler version they are compatible with
Yeah, I think we already agreed on the feature of putting the version in the main roc file of a platform or app, so the supported version is clear.
Luke Boswell (Jan 29 2025 at 11:04):Sounds good. Why do we need the TESTING thing though? Let's just bump the breaking number if we want it to be clearly a new one.
Anton (Jan 29 2025 at 11:04):We can do away with TESTING after today assuming the release goes right
Brendan Hansknecht (Jan 30 2025 at 01:28):This is awesome @Anton. I think it will be really useful to start enabling this new flow even if though manual version and best effort version bumping. My time dried up after the holidays and I have not been able to look into anything automated for this
Last updated: Jun 16 2026 at 16:19 UTC