docs(gc): policy gate defaults said OFF while the code defaults ON (#6987)

[proggeramlug]

Fixes #6987.

What

Two GC policy gates documented themselves as default OFF while defaulting ON.

site	said	actually
gc_incremental_enabled (policy.rs:291)	"EXPERIMENTAL — default OFF"	DEFAULT ON (#6180 flip) — stated in its own body comment eight lines below
gc_safepoint_moving_minor (policy.rs:1396)	"gated by gc_moving_safepoint_enabled (default off)"	that accessor is !matches!(env, "0"|"off"|"false") — default ON

gc_moving_loop_polls_enabled (policy.rs:320) also says "opt-in, default OFF" and that one is accurate (matches!(env, "1"|"on"|"true")) — left unchanged.

Why this is not a cosmetic nit

It changed a merge decision. PR #6972 dismissed the production-reachability of #6970 on the grounds that gc_check_trigger forces the conservative scan on both automatic arms. That reasoning depends on incremental mode being off. It is on, so budgeted cycles skip the conservative subphase structurally (gc/cycle.rs, classifier mode), independent of any guard.

Measured with PERRY_GC_TRACE=1 and no environment variables set: 3 completed cycles, 2 with conservative_root_count = 0. A compiled program completes precise-roots-only cycles in its shipped configuration today.

The #6972 conclusion was reached honestly from the documented behaviour and was wrong because the documentation was wrong. Two separate investigations tripped over these comments within hours of each other.

So the fix adds more than corrected defaults: it records why the incremental default is load-bearing for rooting arguments, not just pause times, so the next reader doesn't repeat the inference.

Scope

Comment-only — no behaviour change, no code touched.

A test asserting the defaults was considered and deliberately not included here. Both gates cache in a OnceLock over a process-global env read, so an in-process assertion is order-dependent and would need either a subprocess harness or extracting the decision into a pure fn(Option<&str>) -> bool helper. That refactor touches GC policy while several rooting PRs are in flight against neighbouring code, and it is the kind of change that deserves its own review rather than riding along with a doc correction. #6987 stays open for it.

Validation

cargo fmt --all -- --check clean. No code paths modified, so no behavioural verification is claimed or needed.

Summary by CodeRabbit

• Documentation
  • Updated garbage-collection configuration documentation to accurately reflect current default settings.
  • Clarified that incremental collection and moving minor safepoints are enabled by default.
  • Added context about how these settings affect collection behavior in shipped configurations.

[coderabbitai]

📝 Walkthrough

Walkthrough

The change corrects documentation for two garbage-collection policy gates whose implementations default to ON, adds their kill-switch details, and records how the stale documentation affected reasoning about incremental collection and precise-root-only cycles.

Changes

GC policy documentation

Layer / File(s)	Summary
Correct GC gate defaults crates/perry-runtime/src/gc/policy.rs, changelog.d/6989-gc-policy-default-docs.md	The incremental old-generation collector and moving minor safepoint gate are documented as default ON, with updated kill-switch and behavior notes in the policy comments and changelog.

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

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes address #6987 by correcting both stale GC gate defaults and documenting the incremental-mode rooting impact.
Out of Scope Changes check	✅ Passed	The PR stays within scope with documentation-only updates and a changelog note, with no unrelated code changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title accurately summarizes the doc-only fix to GC policy defaults and references the linked issue.
Description check	✅ Passed	The description covers the summary, concrete changes, related issue, scope, and validation, with only minor template formatting omissions.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/6987-gc-policy-default-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{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 `@crates/perry-runtime/src/gc/policy.rs`:
- Around line 1405-1406: Update the documentation comment for
gc_moving_safepoint_enabled to list every supported disabling value—0, off, and
false—in the PERRY_GC_MOVING_SAFEPOINT kill-switch description, keeping the
default-enabled behavior documented.

🪄 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: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0fe72633-47c7-4ab6-8d40-314a77ae9df1

📥 Commits

Reviewing files that changed from the base of the PR and between e70ffe2 and 801d04b.

📒 Files selected for processing (2)

• changelog.d/6989-gc-policy-default-docs.md
• crates/perry-runtime/src/gc/policy.rs

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Document all accepted disabling values.

The accessor is documented as disabling the gate for 0, off, or false, but this comment lists only PERRY_GC_MOVING_SAFEPOINT=0. Include all supported values so the policy comment matches the actual configuration contract.

🤖 Prompt for 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.

In `@crates/perry-runtime/src/gc/policy.rs` around lines 1405 - 1406, Update the
documentation comment for gc_moving_safepoint_enabled to list every supported
disabling value—0, off, and false—in the PERRY_GC_MOVING_SAFEPOINT kill-switch
description, keeping the default-enabled behavior documented.