Skip to content

F18.7 — A managed block's end marker can sit at a different indent

State Closed
Parent E18
Iteration Release 8
Start Date 2026-11-13
Closed Date 2026-11-13
Predecessors F18.2
Source Owner request, 2026-11-11

Stories: 2 Closed

Story State Depends on
S18.7.1 — ManagedBlock takes an optional end_indent Closed —
S18.7.2 — Prepare rn-forge-commons 0.9.0 Closed S18.7.1

ManagedBlock writes both of its markers at one indent. A YAML formatter moves a comment that ends a block to the left margin, so a block whose body is indented but whose last line is the end marker cannot stay formatter-clean: the begin marker belongs at two spaces and the end marker at column 0. A consumer works around it today by subclassing ManagedBlock and overriding the private _marker. This feature adds the public field that makes the subclass unnecessary, and releases rn-forge-commons 0.9.0 with it.

Design

ManagedBlock in rn_forge.commons.fs.blocks gained an optional end_indent field after indent. None (the default) makes the end marker use indent, so every existing caller renders the same bytes; any other value, including "", is the end marker's own leading whitespace, and it is not validated, as indent is not. _locate already compares stripped lines, so it finds a marker at any indent.

Release. ADR-0004 bumps the minor before 1.0 for a breaking change and the patch otherwise, and this change is additive. The owner asked for a minor release, rn-forge-commons 0.8.1 to 0.9.0, and [Unreleased] already held a changed default (log redaction on). A 0.x minor is outside every dependent's <0.9 ceiling, so the release also widened six dependents' ceilings (S18.7.2).

S18.7.1 — ManagedBlock takes an optional end_indent

State: Closed · Depends on: —

Tests first, in packages/rn-forge-commons/tests/fs/test_blocks.py, beside test_indent_applies_to_markers_only in class TestMarkers (the first five) and in a new class TestEndIndent after TestRender (the rest). Run them and show them failing (TypeError: ... unexpected keyword argument 'end_indent') before the build.

  1. test_s18_7_1_1_end_indent_defaults_to_indent: ManagedBlock("n", indent=" ").end == " # END n", and ManagedBlock("n", indent=" ", end_indent=None).render("", "- a\n") equals ManagedBlock("n", indent=" ").render("", "- a\n").
  2. test_s18_7_1_2_end_indent_applies_to_the_end_marker_only: block = ManagedBlock("n", indent=" ", end_indent=""); block.begin == " # BEGIN n"; block.end == "# END n".
  3. test_s18_7_1_3_html_end_indent: ManagedBlock("n", comment="<!--", indent=" ", end_indent=" ").end == " <!-- END n -->".
  4. test_s18_7_1_4_render_writes_begin_indented_and_end_at_the_margin: ManagedBlock("n", indent=" ", end_indent="").render("", "- a\n") == " # BEGIN n\n- a\n# END n\n".
  5. test_s18_7_1_5_end_indent_is_not_validated: ManagedBlock("n", indent=" ", end_indent="\t") and ManagedBlock("n", end_indent=" ") construct without error, as indent does.
  6. test_s18_7_1_6_extract_reads_either_end_form: with block = ManagedBlock("n", indent=" ", end_indent=""), both block.extract(" # BEGIN n\n- a\n# END n\n") and block.extract(" # BEGIN n\n- a\n # END n\n") return "- a\n".
  7. test_s18_7_1_7_render_replaces_either_end_form: the same block, given each of the two texts of the previous test and body "- b\n", returns " # BEGIN n\n- b\n# END n\n" from both.
  8. test_s18_7_1_8_remove_and_round_trip: for the same block, block.remove(block.render("head\n", "- a\n")) == "head\n" and block.render(block.render("head\n", "- a\n"), "- a\n") equals block.render("head\n", "- a\n").
  9. test_s18_7_1_9_default_output_is_unchanged: for a table of ManagedBlock("n"), ManagedBlock("n", comment="<!--") and ManagedBlock("n", indent=" "), the render("head\n", "x\n") result equals the literal bytes the pre-change code wrote, written out in the test ("head\n\n# BEGIN n\nx\n# END n\n", "head\n\n<!-- BEGIN n -->\nx\n<!-- END n -->\n" and "head\n\n # BEGIN n\nx\n # END n\n").

Outcome: the field, its docstring entry, the _marker change and the changelog entry shipped as designed.

Acceptance:

  • The nine tests pass, and the rest of tests/fs/test_blocks.py passes unchanged.
  • uv run pyright and uv run ruff check . and uv run ruff format --check . pass.
  • The package site builds with --strict.
  • Not scriptable: the owner reads the _marker diff for any change to the default path.

S18.7.2 — Prepare rn-forge-commons 0.9.0

State: Closed · Depends on: S18.7.1

Version bumps are made at the release cut, when the release's page is approved (the release runbook, Before the merge); this story is that preparation for commons alone. The tag, the GitHub Release and the PyPI upload are made by CI on the merge to main, which the owner approves; no story builds them.

Outcome: rn-forge-commons is at 0.9.0, the six dependents' ceilings are widened to <0.10 with their floors unchanged, and their own versions and the ## [Unreleased] heading are left to the release cut. uv run rn-forge-devops requirements failed before the widening and passes after it.

Acceptance:

  • uv run rn-forge-devops requirements exits 0.
  • packages/rn-forge-commons/pyproject.toml declares version = "0.9.0", and uv run pytest passes for the workspace.
  • uv lock --check passes.
  • Not scriptable (the owner judges): approving the release, merging to main, and confirming rn-forge-commons-v0.9.0 is on PyPI afterwards, per the runbook's After the merge.

Acceptance

set -euo pipefail
cd packages/rn-forge-commons
uv run pytest -q tests/fs/test_blocks.py                      # S18.7.1
uv run --group docs mkdocs build --strict                     # S18.7.1
cd ../..
uv run rn-forge-devops requirements                           # S18.7.2
grep -qx 'version = "0.9.0"' packages/rn-forge-commons/pyproject.toml   # S18.7.2
uv lock --check                                               # S18.7.2

The owner approves the release and confirms the PyPI upload after the merge.