docs(migration): Create migrate-to-minimal-session.md by jessie-minimal · Pull Request #1003 · gominimal/minimal

jessie-minimal · 2026-07-28T22:36:19Z

Summary

Added a migration guide for Minimal One

Testing

Checklist

Docs updated if behavior changed
BREAKING CHANGE: footer present if this is a breaking change

Note

Add migration guide for moving to the Minimal Sessions architecture in v0.5.0

Adds migrate-to-minimal-session.md covering the transition from legacy minimal to the new min command introduced in v0.5.0.

Documents that legacy minimal is preserved but tasks are unsupported in v0.5.0, with uninstall instructions and a pointer to min installation docs
Describes Linux backward compatibility via mip (Minimal-In-Process), including a command mapping from minimal to mip
Covers minimal.toml schema changes: harness renamed to stack, profiles deprecated, and a new [session] section added
Documents session lifecycle commands (min activate, min attach, --attach) and instructions for migrating profile env vars and packages to session.vars and session.packages

Changes since #1003 opened

Introduced [session] configuration section to replace interactive task definitions, with migration guidance from shell, bash, and agent task types to session-based workflows using min activate and min attach commands [a9a090f]
Documented renaming of [harness] configuration section to [stack] in minimal.toml, with guidance that [upstream] and [outputs] sections remain unchanged, [defaults] profiles are deprecated, and tasks split between interactive (moved to sessions) and non-interactive (remain as tasks) [a9a090f]
Replaced minimal CLI command with mip command on Linux, providing command mapping table showing old versus new command syntax and noting that in-VM min add command remains unchanged [a9a090f]
Documented migration path from profile.env_vars to session.vars and from profile.packages to session.packages as part of profiles deprecation [a9a090f]
Restructured migration guide with consolidated warnings about task support in v0.5.0, repositioned installation and uninstallation instructions, clarified version check commands, and recommended parallel installation of min alongside legacy minimal [a9a090f]

^{Macroscope summarized 2969ef5.}

Summary by CodeRabbit

Documentation
- Expanded the “Minimal Sessions Migration Guide” for Linux/macOS upgrades to the Sessions architecture (v0.5.0+).
- Added a v0.5.0 warning that interactive tasks must be migrated and that non-interactive, job-like workflows no longer support tasks.
- Clarified minimal → min, including uninstall steps for legacy minimal and updated minimal.toml migration: rename harness → stack, add [session], and deprecate profiles with a mapping to session vars/packages.
- Documented Linux installer behavior introducing mip as an in-place command mapping for minimal.

coderabbitai · 2026-07-28T22:41:36Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

📝 Walkthrough

Walkthrough

Updates the v0.5.0+ migration guide with command compatibility, Linux mip behavior, minimal.toml schema changes, task and profile migration, and session lifecycle commands.

Changes

Sessions migration documentation

Layer / File(s)	Summary
Migration instructions `docs/guide/migrate-to-minimal-session.md`	Documents version checks, the `minimal` to `min` transition, Linux `mip` compatibility, legacy uninstall instructions, installation guidance, and `minimal.toml` section mappings.
Session workflow migration `docs/guide/migrate-to-minimal-session.md`	Explains non-interactive task incompatibility, migration of interactive tasks and profile fields to `[session]`, and session lifecycle commands.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Possibly related PRs

gominimal/minimal#737: Renames CLI targets and scripts from minimal to min, matching the documented command transition.
gominimal/minimal#863: Updates related minimal.toml, session, stack, and CLI reference documentation.
gominimal/minimal#939: Covers the Sessions concept and attach semantics referenced by this guide.

Suggested reviewers: twitchyliquid64

Poem

A rabbit hops through config land,
With session notes held in hand.
Tasks change their way,
Stacks guide the day,
And min helps migrations stand.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title is concise and accurately reflects the new migration guide being added.
Description check	✅ Passed	The description includes a summary and checklist, but the testing section is left blank.

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/guide/migrate-to-minimal-session.md`:
- Around line 48-52: Rewrite the migration text around the `[session]` section
so it clearly states that `[session]` defines interactive environments for
shell, bash, and interactive agent tasks. Correct “Task defined with” to plural
wording and explicitly instruct that tasks with `interactive = true` should be
migrated to session definitions, preserving the existing configuration
reference.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 9f67abbd-a84a-48f1-a57a-09f0f6303d5f

📥 Commits

Reviewing files that changed from the base of the PR and between bfd0812 and e4eecc7.

📒 Files selected for processing (1)

docs/guide/migrate-to-minimal-session.md

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/guide/migrate-to-minimal-session.md`:
- Around line 11-18: Update the migration guidance around the `tasks`
compatibility warning and `uninstall.sh` command so users who rely on
non-interactive tasks keep `minimal` installed alongside `min`. Make the
uninstall instruction conditional on users no longer needing `minimal`, and
clarify the side-by-side installation requirement.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2e820f0b-fab3-48b4-8162-3777bc592e68

📥 Commits

Reviewing files that changed from the base of the PR and between bfd0812 and e4eecc7.

📒 Files selected for processing (1)

docs/guide/migrate-to-minimal-session.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/guide/migrate-to-minimal-session.md`:
- Around line 22-27: Correct the Linux migration examples in the documented
command mapping so the `minimal add` example uses `mip add` rather than `mip
update`, while leaving the `run` and `update` mappings unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d2362485-ac74-40f7-a24b-17aba8b53a06

📥 Commits

Reviewing files that changed from the base of the PR and between 0bfae95 and 12c4cdd.

📒 Files selected for processing (1)

docs/guide/migrate-to-minimal-session.md

coderabbitai Bot reviewed Jul 28, 2026

View reviewed changes

Comment thread docs/guide/migrate-to-minimal-session.md Outdated

coderabbitai Bot reviewed Jul 28, 2026

View reviewed changes

Comment thread docs/guide/migrate-to-minimal-session.md Outdated

jessie-minimal changed the title ~~Create migrate-to-minimal-session.md~~ docs: Create migrate-to-minimal-session.md Jul 28, 2026

jessie-minimal changed the title ~~docs: Create migrate-to-minimal-session.md~~ docs(migration): Create migrate-to-minimal-session.md Jul 28, 2026

jessie-minimal and others added 8 commits July 28, 2026 17:12

docs(migration): add minimal sessions migration guide

523ec93

docs(migration): remove old minimal.toml section

b5409bf

docs(migration): document session activate and attach commands

740a075

docs(migration): apply code review suggestions

d660d2f

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

docs(migration): mention deprecation of profiles

f8d14bc

docs(migration): document uninstall command

76d373c

docs(migration): drop stale going-forward qualifier

f9548fb

docs(migration): add exception cases for Linux

12c4cdd

jessie-minimal force-pushed the minimal-one-migration-guide branch from cea1f52 to 12c4cdd Compare July 29, 2026 00:12

coderabbitai Bot reviewed Jul 29, 2026

View reviewed changes

Comment thread docs/guide/migrate-to-minimal-session.md Outdated

jessie-minimal added 2 commits July 28, 2026 17:19

docs(migration): fix mip add command mapping

564e181

docs(migration): clarify mip and link cli-mip reference

2969ef5

norrietaylor approved these changes Jul 29, 2026

View reviewed changes

mitodrummer approved these changes Jul 29, 2026

View reviewed changes

docs(migration): restructure guide for concision and readability

a9a090f

jessie-minimal merged commit f46e867 into main Jul 29, 2026
29 checks passed

jessie-minimal deleted the minimal-one-migration-guide branch July 29, 2026 18:01

coderabbitai Bot mentioned this pull request Jul 29, 2026

docs(migration): fix min session commands in activate/attach example #1090

Merged

2 tasks

Navigation Menu

Uh oh!

docs(migration): Create migrate-to-minimal-session.md - #1003

docs(migration): Create migrate-to-minimal-session.md#1003
jessie-minimal merged 11 commits into
mainfrom
minimal-one-migration-guide

jessie-minimal commented Jul 28, 2026 •

edited by macroscopeapp Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 28, 2026 •

edited

Loading

Reviews paused

Walkthrough

Changes

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

jessie-minimal commented Jul 28, 2026 • edited by macroscopeapp Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Testing

Checklist

Add migration guide for moving to the Minimal Sessions architecture in v0.5.0

Changes since #1003 opened

Summary by CodeRabbit

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Changes

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jessie-minimal commented Jul 28, 2026 •

edited by macroscopeapp Bot

Loading

coderabbitai Bot commented Jul 28, 2026 •

edited

Loading