Merge pull request #496 from roc-lang/prepare-0.23.0-release

Prepare release notes for 0.23.0

Author: lukewilliamboswell

.github/workflows/release.yml

@@ -365,7 +365,31 @@ jobs:
         with:
           name: platform-docs
 
-      - name: Make release notes
+      - name: Select release notes
+        id: release-notes
+        env:
+          RELEASE_VERSION: ${{ needs.build.outputs.release_version }}
+        run: |
+          if [[ -f "docs/releases/${RELEASE_VERSION}.md" ]]; then
+            echo "custom=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "custom=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Use repository release notes
+        if: steps.release-notes.outputs.custom == 'true'
+        uses: roc-lang/release-package/actions/make-release-notes@af2f0cd8662874b825ff3917f4286e793ba18c55
+        with:
+          release_version: ${{ needs.build.outputs.release_version }}
+          release_notes_command: >-
+            python3 scripts/render_release_notes.py
+            "docs/releases/${RELEASE_VERSION}.md" "$RELEASE_NOTES_PATH"
+            --repo "$GITHUB_REPOSITORY"
+            --version "$RELEASE_VERSION"
+            --bundles "$RELEASE_BUNDLES_PATH"
+
+      - name: Generate release notes
+        if: steps.release-notes.outputs.custom != 'true'
         uses: roc-lang/release-package/actions/make-release-notes@af2f0cd8662874b825ff3917f4286e793ba18c55
         with:
           release_version: ${{ needs.build.outputs.release_version }}

docs/releases/0.23.0.md

@@ -0,0 +1,114 @@
+# basic-cli 0.23.0
+
+```roc
+app [main!] { pf: platform "{{PLATFORM_URL}}" }
+```
+
+Requires the Roc new-compiler nightly **`nightly-2026-09-22-e494788`** or later.
+
+## Write the script in Roc, not bash
+
+Most command-line programs eventually need a bash script alongside them. They call `mktemp -d` to get a scratch directory, `cp -r` to stage files, `timeout 300` to stop a stuck build, and a `trap` to clean up afterwards. Those scripts are hard to make portable, the errors come back as exit codes and text, and a child process can easily be left running.
+
+0.23.0 gives basic-cli native APIs for this work, so the whole script can be a Roc program. Arguments are passed straight through without shell quoting. Exit codes, timeouts and output are returned as data you can `match` on. Processes, listeners and temporary directories are cleaned up when your program finishes with them.
+
+Here is a release-staging script that would usually need `mktemp`, `cp -r` and a `trap`:
+
+```roc
+Env.with_temp_dir!(|workspace| {
+    staged = Path.join(workspace, "release")
+    Path.copy_dir!(source, staged)?
+    Path.write_utf8!(Path.join(staged, "RELEASE.txt"), "Prepared with basic-cli\n")?
+    Path.copy_dir!(staged, destination)?   # fails rather than overwrite an existing release
+    Ok({})
+})?
+```
+
+The temporary workspace is deleted whether the callback succeeds or fails. If both the callback and the cleanup fail, you get both errors, not just one. See the full [`filesystem-tools.roc`](https://github.com/roc-lang/basic-cli/blob/0.23.0/examples/filesystem-tools.roc) and [`process-control.roc`](https://github.com/roc-lang/basic-cli/blob/0.23.0/examples/process-control.roc) examples.
+
+## Run and supervise processes
+
+`Cmd` now covers what bash's `timeout`, `tee` and `&` are usually used for:
+
+```roc
+output = Cmd.new("cargo")
+    .args(["build", "--release"])
+    .stdout(Tee)              # stream to the terminal *and* capture
+    .stderr(Tee)
+    .timeout_ms(300_000)      # hard deadline, including draining output
+    .manage_tree(Bool.True)   # on timeout, kill grandchildren too
+    .run!()?
+
+match output.status {
+    Exited(0) => Stdout.line!("Build succeeded")
+    Exited(code) => Err(BuildFailed(code))
+    Signaled(signal) => Err(BuildKilled(signal))
+}
+```
+
+- **`Cmd.run!`** runs a command to completion. A nonzero exit is returned as a status for you to handle, not as an error. Errors are reserved for failures of the command itself: `IO`, `Timeout(partial_output)` and `OutputLimit(partial_output)`. Both limit errors include the output collected before the command was stopped.
+- **`Cmd.spawn!`** starts a process in the background and returns a `Child` handle. Use `pid!`, `wait!`, `try_wait!`, `kill!` and `close!` to manage it. To interact with it, set `.stdin(Pipe)` and `.stdout(Pipe)`, then use `write!`, `read!` and `close_stdin!`.
+- **New builder options:** `cwd`, `stdin`, `stdout` and `stderr` (`Inherit`, `Null`, `Capture`, `Pipe`, `Tee`, and `Bytes` for stdin), `timeout_ms`, `output_limit`, `pending_limit`, `manage_tree` and `merge_stderr`.
+- **Cleanup is automatic.** When your program drops its last reference to a `Child`, the process is terminated and reaped. Call `close!` if you need this to happen at a specific point.
+
+The existing `exec!`, `exec_cmd!`, `exec_output!` and `exec_output_bytes!` helpers now run on the same process engine.
+
+## Files, paths and temporary workspaces
+
+- `Path.copy!` copies a file, including its permissions.
+- `Path.copy_dir!` copies a directory tree to a destination that must not exist yet. `Path.copy_dir_with!` lets you choose whether symlinks are preserved or followed, and whether an existing destination is merged into. Copies that would loop, or where the source and destination overlap, are rejected.
+- `Path.absolute!` makes a path absolute without touching the filesystem. `Path.canonicalize!` resolves an existing path, including symlinks.
+- `Env.create_temp_dir!`, `Env.create_temp_dir_with_prefix!` and `Env.create_temp_dir_in!` create private temporary directories. `Env.with_temp_dir!` also deletes the directory when your callback finishes.
+- `OsStr.to_bytes` returns the raw native bytes of an OS string.
+
+## Servers and timing
+
+- **Accept TCP connections.** `Tcp.listen!(host, port, timeout_ms)` returns a `Tcp.Listener` with `accept!`, `local_port!` and `close!` methods. Listen on port `0` and read `local_port!` to have the OS pick a free port. This is useful for tests and local helper servers.
+- **Measure elapsed time.** `Monotonic.now!` returns nanoseconds (`U64`) from a clock that system clock changes don't affect. Subtract two readings to get a duration. The values are only meaningful within a single run of your program, so don't store them.
+
+## Upgrading from 0.22
+
+**`main!` no longer receives the program name.** `args` now contains only the arguments the user passed, which matches Roc's default platform ([#494](https://github.com/roc-lang/basic-cli/pull/494)). Code that skipped the first element will now **silently drop a real argument**, so check every place that handles `args`:
+
+```roc
+# 0.22
+main! = |args| {
+    user_args = args.drop_first(1)
+    ...
+}
+
+# 0.23
+main! = |args| {
+    # args are already the user's arguments.
+    # Program name, if needed:
+    name = Env.program_name!()?   # Err(ProgramNameUnavailable) if the launcher didn't supply one
+    ...
+}
+```
+
+**Remove `..` from error types in return position.** Roc now makes tag unions in return position open automatically, so basic-cli's signatures are now written without `..` (for example, `Path.read_bytes! : Path => Try(List(U8), [PathErr(IOErr, Path)])`), and yours can be too ([#495](https://github.com/roc-lang/basic-cli/pull/495)). This change is why 0.23.0 needs the nightly listed at the top.
+
+**Captured output is capped at 16 MiB by default.** When stdout and stderr together exceed the limit, the command is cancelled. `run!` returns `OutputLimit(partial_output)`, and the `exec_output*` helpers return `FailedToGetExitCode` with the message "Process output limit exceeded". If a command legitimately produces more output, raise the limit with `.output_limit(bytes)`, or use `.stdout(Inherit)` to send the output straight to the terminal.
+
+**Update the platform URL.** The native host interface changed to support managed resources, so programs built against 0.22 need to be rebuilt against 0.23.0. Mixing hosts and platform sources from different versions is not supported.
+
+## Fixes
+
+- **Windows:** programs no longer hang on exit if they made an HTTP request in the previous ten seconds ([#493](https://github.com/roc-lang/basic-cli/pull/493)).
+- File readers, TCP streams and SQLite statements now release their OS resources as soon as the last reference to them is dropped, instead of at program exit.
+- **SQLite:** fixed a type-inference problem in the row decoders that could cause errors in application code using them. Columns are now looked up by name ([#475](https://github.com/roc-lang/basic-cli/pull/475), 0.22.1).
+- `Path.to_str` errors now combine with other errors in the same function when you use `?` ([#479](https://github.com/roc-lang/basic-cli/pull/479), 0.22.2). With the implicit-open change above, every basic-cli function now behaves this way.
+
+## Documentation and tooling
+
+- The API docs have been revised, with runnable examples for the new process, filesystem and TCP APIs.
+- Contributors can use the new Nix flake devshell with direnv ([#432](https://github.com/roc-lang/basic-cli/pull/432)), and point the test runner at a specific compiler with `ROC=...` ([#477](https://github.com/roc-lang/basic-cli/pull/477)).
+
+## Thanks
+
+Thanks to everyone who contributed to 0.22.1 through 0.23.0: @ageron, @Anton-4, @Karakatiza666, @lukewilliamboswell, @niclas-ahden, @rtfeldman and @thebrandonlucas.
+
+---
+
+- [API documentation](https://roc-lang.github.io/basic-cli/0.23.0/)
+- [Full changelog since 0.22.0](https://github.com/roc-lang/basic-cli/compare/0.22.0...0.23.0)

scripts/render_release_notes.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""Render docs/releases/<version>.md, filling in values only known at release time.
+
+Placeholders:
+  {{PLATFORM_URL}}  URL of the published platform bundle
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from pathlib import Path
+
+
+PLACEHOLDER_RE = re.compile(r"\{\{[A-Z_]+\}\}")
+
+
+def platform_url(repo: str, version: str, bundles_path: Path) -> str:
+    bundles = json.loads(bundles_path.read_text(encoding="utf-8"))
+    if len(bundles) != 1:
+        raise SystemExit(f"expected exactly one release bundle, found {len(bundles)}")
+    return f"https://github.com/{repo}/releases/download/{version}/{bundles[0]['artifact_file']}"
+
+
+def render(template: str, values: dict[str, str]) -> str:
+    rendered = template
+    for name, value in values.items():
+        rendered = rendered.replace("{{" + name + "}}", value)
+
+    unknown = sorted(set(PLACEHOLDER_RE.findall(rendered)))
+    if unknown:
+        raise SystemExit(f"unknown release notes placeholders: {', '.join(unknown)}")
+    return rendered
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("template", type=Path)
+    parser.add_argument("output", type=Path)
+    parser.add_argument("--repo", required=True)
+    parser.add_argument("--version", required=True)
+    parser.add_argument("--bundles", type=Path, required=True)
+    args = parser.parse_args()
+
+    values = {"PLATFORM_URL": platform_url(args.repo, args.version, args.bundles)}
+    args.output.write_text(render(args.template.read_text(encoding="utf-8"), values), encoding="utf-8")
+
+
+if __name__ == "__main__":
+    main()