Skip to content

F23.1 — Help text reads as written, and a command starts quietly

State Closed
Parent E23
Iteration Release 9
Start Date 2026-11-17
Closed Date 2026-11-17
Predecessors —
Source kiln F7.7, 2026-11-14

Stories: 3 Closed

Story State Depends on
S23.1.1 — Square brackets in a docstring show in --help Closed (2026-11-17) —
S23.1.2 — --help shows a docstring's prose, not its sections Closed (2026-11-17) —
S23.1.3 — A command starts with no logger notice, and a timestamp shows its milliseconds once Closed (2026-11-17) —

A tool built on rn-forge-cli shows its docstrings as written in --help, and prints nothing on stdout or stderr that the command did not ask for.

Context

These were seen running kiln 0.1.0 from feature/v1 (kiln 21c8dc4), on rn-forge-cli 0.1.x and rn-forge-commons 0.8.x:

  • kiln pin --help shows "Set the current repository's ref" where the docstring says `[kiln] ref`, and kiln new --help loses [project] in the same way. Typer's Rich markup mode reads [kiln] as a style tag and drops it.
  • kiln new --help prints the docstring's Raises: section ("AppException: --archetype is missing…"). CommandSpec.help defaults to the target's whole docstring (cli/surface.py).
  • Every command, kiln version included, prints … kiln.notice NOTICE … App Logger Configured -> INFO | None before its output. AppLogger.configure logs it at NOTICE (logging/logger.py).
  • That line's timestamp is 20:07:57,036,036. The console format is %(asctime)s,%(msecs)03d, and the default asctime already ends in ,<msecs>.

S23.1.1 — Square brackets in a docstring show in --help

State: Closed (2026-11-17)

Acceptance:

  • A command whose docstring contains `[kiln] ref` and [project] name shows both literally in its --help, in the command list and on its own page.
  • Help that relies on Rich markup or Markdown styling still renders. The test checks one styled element, so the fix escapes brackets rather than turning markup off.
  • The tests use a CliApp built from a TOML surface, the way a tool builds one.

S23.1.2 — --help shows a docstring's prose, not its sections

State: Closed (2026-11-17)

Acceptance:

  • A target's default help is its summary line and description, ending before the first Google-style section (Args:, Arguments:, Returns:, Raises:, Yields:, Examples:, Note:). An explicit help in the surface is used as it is written.
  • A command whose docstring has a Raises: section shows no Raises: and no exception name in --help. This is a test.
  • The cli guide says where help text comes from and where it is cut.

S23.1.3 — A command starts with no logger notice, and a timestamp shows its milliseconds once

State: Closed (2026-11-17)

Acceptance:

  • At the default level, configuring the logger writes nothing to stdout or stderr. The "App Logger Configured" record is logged at DEBUG, or the package's verbose level, and shows with --log-level debug.
  • A console record's timestamp has exactly one millisecond field (HH:MM:SS,mmm). The test matches the formatted record with a regex.
  • rn-forge-commons and rn-forge-cli are released with these fixes in ranges that kiln's <0.9 and <0.2 caps accept, or kiln's pin row names the new floors.

Acceptance

set -euo pipefail
task test -- rn-forge-cli      # S23.1.1 S23.1.2
task test -- rn-forge-commons  # S23.1.3

Not scriptable: kiln F7.7's S7.7.4 run shows the three fixes in kiln --help, kiln pin --help, kiln new --help and kiln version.