Rick Hull (Jan 16 2026 at 15:22): Rick Hull (Jan 16 2026 at 15:22):Is it time to inform curious new users about the new compiler split? e.g. somewhere prominent on roc-lang.org? If I were onboarding a new dev, I might tell them something like: Roc-alpha-4 is stable and relatively frozen but also somewhat deprecated. All of the docs are oriented to the old Roc system. The new Roc system is much different, call it Roc-nightly. Different syntax, different features, different builtins (stdlib). Currently, this has the normal expectations of "bleeding edge development" with underspecified docs that are scattered throughout the ecosystem. Here is a rough guide: ...
Anton (Jan 16 2026 at 15:23):Yeah, that sounds good to me. I will wait a bit for others to weigh in before adding it.
Rick Hull (Jan 16 2026 at 15:28):Shall I create an issue and go from there?
nandi (Jan 16 2026 at 15:33):There seems to be a lot of new users joining confused by the compiler split. I feel like there's this awkward tension between not broadcasting the new compiler too loudly since it's still very nascent, and broadcasting the new compiler because it's the preferred way to do things going forward and all the old stuff is essentially deprecated. Not just the language runtime but fundamental things like syntax etc
Anton (Jan 16 2026 at 15:33):Shall I create an issue and go from there?
Yes, thanks :) Feel free to keep it a bit vague so that we can discuss specifics here and avoid duplication.
Rick Hull (Jan 16 2026 at 15:34):https://github.com/roc-lang/roc/issues/9040
Anton (Jan 16 2026 at 15:35):awkward tension between not broadcasting the new compiler too loudly since it's still very nascent
We can make the current state clear on the website
Luke Boswell (Jan 16 2026 at 22:42):Is it time to inform curious new users about the new compiler split?
I am not sure if we are there yet. But I know for certain this is something Richard has put a lot of thought into. In the last meetup he talked about an idea for an awesome blog post and video he had in mind. :smiley:
Luke Boswell (Jan 16 2026 at 22:43):There was this gist https://gist.github.com/rtfeldman/77fb430ee57b42f5f2ca973a3992532f which was intended for contributors in zulip and kind of got shared around the internet :smiley:
nandi (Jan 17 2026 at 00:41):Anton said:
Shall I create an issue and go from there?
Yes, thanks :) Feel free to keep it a bit vague so that we can discuss specifics here and avoid duplication.
https://github.com/ghostty-org/ghostty/issues/3558
Luke Boswell (Jan 17 2026 at 00:46):That's a really interesting approach the ghostty team have. I think I like it. Interested to hear what others think.
nandi (Jan 17 2026 at 00:49):I was tempted to make a suggestion to close our over 1000 open issues and then have a channel/topic where people discuss the ones they want to reopen
nandi (Jan 17 2026 at 00:54):my hesitation is that the new compiler is so nascent, having that many issues doesn't necessarily seem too unreasonable
Brendan Hansknecht (Jan 17 2026 at 00:57):I feel like naturally opensource gets issues of various froms:
With how roc and github work:
general ideas from users, helpdesk request, and complaints of whatever form definitely belong in zulip
drop by bugs often make sense to start in zulip but if they have enough info are fine as issues (they often don't have enough info though.
concrete proposal also belong in zulip or maybe in rfcs
projects from contibutors actually do below in github
tasks from contributors also belong in github, but they are complex. If they are really small, they get lost in the miles of bugs, but also the small ones like that are often best for new contributors.
Brendan Hansknecht (Jan 17 2026 at 00:57):Anyway, all that to say that the ghostty idea is pretty reasonable. Funnel through zulip first.
Rick Hull (Jan 19 2026 at 04:14):One inchoate idea I have is to make a roc-support-bot (or LLM). I don't quite mean this literally, more conceptually or logically. When a new user needs support, the first line could be a conversational LLM, or agentic. When that avenue is exhausted, take it to Zulip. Zulip decides whether to promote to an Issue.
Obviously, I am True Believer (tm) in LLMs, but only because they have greatly accelerated my progress (in some direction, heh) in understanding (primarily) and writing working code (for various definitions of working) in unfamiliar arenas. Not only in Roc. They are not quite the bees' knees yet, but they already augment my own perception of my performance in the areas that matter to me.
Luke Boswell (Jan 19 2026 at 07:06):Like RocGPT :smiley: -- not sure when this was last updated .. @Anton might know
Artem (Jan 19 2026 at 07:58):Doubling the idea of site update. When I came in to try a new compiler, I was confused about relevance of info in tutorial. I thought it somehow should reflect new compiler changes. So until I searched for new interface in compiler docs, I did not understand whether std changed or I'm doing something else wrong
Just having a warning would help a lot. And also this information might be relevant for new users who want to try Roc. I'm sure most would wait for new compiler if they new that everything is about to change
Anton (Jan 19 2026 at 09:11):Luke Boswell said:
Like RocGPT :smiley: -- not sure when this was last updated .. Anton might know
Not for a very long time, I think they require a paid chatGPT account for the user so it's not an ideal solution.
Anton (Jan 19 2026 at 09:19):One inchoate idea I have is to make a roc-support-bot (or LLM). I don't quite mean this literally, more conceptually or logically.
A simple version of this would be to make a general Roc prompt that explains all the basics, has links to useful resources, contains instructions for searching through github issues and zulip, etc.
People like to use their own LLM.
Rick Hull (Jan 19 2026 at 10:43):People like to use their own LLM.
yes, exactly. I need some handholding myself, quite a lot actually, and so not only am I developing a platform as my 'hello world', I am simultaneously feeding everything I've learned into a claude skill, so I am learning how to make the LLM learn to be my handholder.
I think this roc-lang claude skill that I'm working on is a good entry point, but I'm not sure how well it's going so far.
Rick Hull (Jan 19 2026 at 10:54):which "new compiler docs" are the most helpful? where should I start my search?
Anton (Jan 19 2026 at 11:20):which "new compiler docs" are the most helpful?
https://github.com/roc-lang/roc/blob/main/src/build/roc/Builtin.roc
https://github.com/roc-lang/roc/blob/main/test/fx/all_syntax_test.roc
You can also search through the test folder or test/snapshots if you the above links did not contain a useful example.
Anton (Jan 19 2026 at 11:20):where should I start my search?
Do you mean your search for all the info needed for your claude skill?
Rick Hull (Jan 19 2026 at 11:34):i've got those 2 in the bag, plus langref/* and my LLMs have poked all through src/ and test/snapshots/ I was hoping there was more "documentation", but totally understandable that we're not there yet.
Rick Hull (Jan 19 2026 at 11:39):"my search" is both for myself and a claude skill. in general, my approach has been to feed good information to an LLM with fresh context. then I ask the LLM to explain things to me. so far, when it tries to write roc-nightly code, it makes a lot of mistakes. All of its mistakes seem plausible to me, so I think it's doing a much better job than I could, given the source material and human limits on time and understanding.
This is my best result so far, according to my own quite limited judgment: https://gist.github.com/rickhull/ad9a8ca20adf332242524d3b1db01e68
It's a lot, but tries to be comprehensive. I would consider it a skeleton. The explanation of "tag union" is kinda cringe. I am treating this as my lodestar for now, but if anyone sees anything wrong or misleading, please let me know.
Anton (Jan 19 2026 at 13:18):This is my best result so far, according to my own quite limited judgment: https://gist.github.com/rickhull/ad9a8ca20adf332242524d3b1db01e68
It looks pretty good from a quick scan :)
Alec Gargett (Jan 19 2026 at 23:54):I think it's important to let people know ASAP how much of the documentation that's available won't apply to the new compiler. The website emphasises that the language is in alpha, but some won't realise how much of the syntax they are learning and writing will stop working.
What do you all think of providing a warning that includes links to the Advent of Code document at the top of the existing tutorial and installation pages? That gives people the choice and might reduce the risk of putting people off starting learning altogether, while also ensuring they are using the right compiler for their goals.
Alec Gargett (Jan 20 2026 at 00:11):Luke Boswell said:
That's a really interesting approach the ghostty team have. I think I like it. Interested to hear what others think.
Yes I like it too. Of course, it's unnecessary in smaller projects, and there might be other ways to mark certain issues as ready to be implemented, but in a project with over 1000 open issues it's probably a good idea. I think it's worth starting a separate Zulip thread on this if it hasn't been already. There might need to be a system developed for determining when a proposal gets promoted to an Issue, including this one.
Alec Gargett (Jan 20 2026 at 00:15):Rick Hull said:
When a new user needs support, the first line could be a conversational LLM, or agentic. When that avenue is exhausted, take it to Zulip. Zulip decides whether to promote to an Issue.
Yes, I think it's a good idea to support the use of LLMs before Zulip for both compilers. The head of the tutorial already does a decent job of encouraging LLM use by providing links to the LLM-friendly version of the docs, but the LLM --> Zulip pipeline could be made clearer at the top of that page and at the top of the docs themselves, with docs for each compiler.
Richard Feldman (Jan 20 2026 at 02:20):I'm totally up for putting a warning message on roc-lang.org - if anyone wants to contribute that, I'd appreciate it!
Rick Hull (Jan 20 2026 at 03:00):If I were onboarding a new dev, I might tell them something like:
Roc-alpha-4is stable and relatively frozen but also somewhat deprecated. All of the docs are oriented to the old Roc system. The new Roc system is much different, call itRoc-nightly. Different syntax, different features, different builtins (stdlib). Currently, this has the normal expectations of "bleeding edge development" with underspecified docs that are scattered throughout the ecosystem. Here is a rough guide: ...
Alec Gargett (Jan 20 2026 at 04:52):I would simplify it a bit:
"The following is based on the stable Rust compiler, and some of the syntax will not work with the new Zig compiler. If you would like to experiment with the unstable Zig compiler, you can try the Advent of Code guide." (with hyperlink)
That same text can be used for the top of the tutorial, examples and docs pages.
Here's a commit for the tutorial page that I'll do a PR for if no one objects:
https://github.com/roc-lang/www.roc-lang.org/compare/main...alecgargett:www.roc-lang.org:patch-2
Alec Gargett (Jan 20 2026 at 05:02):I think it's better to link to the Advent of Code guide only, and people can leave comments on that guide with links to other resources.
Anton (Jan 20 2026 at 09:17):Thanks @riverstone I'll check that out
Anton (Jan 20 2026 at 09:19):call it
Roc-nightly
This may be confusing, we've had nightlies of the old compiler for many years. We typically use "new/zig compiler" and I think that's been the best name so far.
Alec Gargett (Jan 20 2026 at 10:11):OK I've done two PRs on the website repo for Docs and Tutorial and one PR on the examples repo.
Alec Gargett (Jan 20 2026 at 10:11):I should have use my real name on here haha. Any admin can change it if you like.
Rick Hull (Jan 20 2026 at 13:15):i'm sure I will find it, but what is the "Advent of Code document"? I can tell AoC has some importance to Roc, but when I poked around, it looks like there was something from several years ago. Was last year's about the new compiler?
Anton (Jan 20 2026 at 13:59):"Advent of Code document"
Is it this: https://gist.github.com/rtfeldman/f46bcbfe5132d62c4095dfa687bb9aa4
I don't think we have another document
it looks like there was something from several years ago
Yeah, people do AoC with Roc every year :)
Was last year's about the new compiler?
Yes but it was not really ready to shine yet
Rick Hull (Jan 20 2026 at 14:34):oh nice! how accurate is it today?
Anton (Jan 20 2026 at 14:35):Should be pretty solid, you just need to use the latest release of the platform https://github.com/lukewilliamboswell/roc-platform-template-zig/releases/tag/0.6
Rick Hull (Jan 20 2026 at 14:37):that's what I am basing off of, or HEAD as of a week ago
Rick Hull (Jan 20 2026 at 14:45):LLM analysis of the 2025 AoC doc: https://gist.github.com/rickhull/da5824695d632ca34be686b4e9c84ad6
Anton (Jan 20 2026 at 14:49):I'll make a todo for an updated version
Rick Hull (Jan 20 2026 at 15:14):Awesome! this is a little bit of a validation of my roc-language skill. I started a new LLM session, loaded the skill, and let it rip on the AoC doc.
I am ready to share this skill -- host it somewhere and accept PRs. Open to suggestions.
I am also considering renaming it to roc-lang. Open to suggestions.
Anton (Jan 20 2026 at 15:35):I am ready to share this skill -- host it somewhere and accept PRs. Open to suggestions.
We could include it in github.com/roc-lang/roc and make a new init subcommand roc init that produces a starter roc project with a .claude/skills/roc-lang. Thoughts welcome
Rick Hull (Jan 20 2026 at 15:38):It eager loads a 400ish-line ROC_TUTORIAL_CONDENSED.md, which was LLM generated purely from Builtin.roc and all_syntax_test.roc
Then it has for reference, full loading, or searching:
Builtin.rocall_syntax_test.rocROC_LANGREF_TUTORIAL.md 2300ish line LLM-generated doc from a long opus run on the roc-lang/roc repoI would suggest someone other than me make a new topic, maybe not in #beginners for further discussion.
Alec Gargett (Jan 20 2026 at 21:28):Rick Hull said:
LLM analysis of the 2025 AoC doc: https://gist.github.com/rickhull/da5824695d632ca34be686b4e9c84ad6
Thanks Rick. Could you post a link to all of your relevant docs in the comments on the Advent of Code doc?
Rick Hull (Jan 20 2026 at 21:30):short answer: yes. long answer: they are now hosted in a (presumably temporary) repo: https://github.com/rickhull/roc-init see the #ideas channel for more details; PRs welcome
Alec Gargett (Jan 20 2026 at 21:40):OK. I'd be fine with updating the NOTE on the Tutorial page to include a link to this:
"...Advent of Code guide and LLM-generated documents".
Alec Gargett (Jan 20 2026 at 21:43):The update to the Examples.md page hasn't gone live yet unlike the .html. Does the html builder need to be triggered manually?
Rick Hull (Jan 20 2026 at 22:15):within roc-init/docs, the UPCASE.md docs are (somewhat coincidentally) LLM-generated, and the OtherCase.md docs are handwritten (presumably)
Rick Hull (Jan 20 2026 at 22:22):I think that we can make (some of) the LLM-suggested changes to AoC25, and get rid of the analysis doc. i think @Anton has that in a TODO
Rick Hull (Jan 20 2026 at 22:27):This is the tracking issue, to my knowledge: https://github.com/roc-lang/roc/issues/9040
Alec Gargett (Jan 20 2026 at 23:54):Sounds good
Anton (Jan 21 2026 at 09:25):Alec Gargett said:
The update to the Examples.md page hasn't gone live yet unlike the .html. Does the html builder need to be triggered manually?
I have triggered a new build, the website is not updated automatically if only the examples repo changed.
Alec Gargett (Jan 21 2026 at 10:03):Thanks Anton
Last updated: Feb 20 2026 at 12:27 UTC