docs: add guided next-step hints for release make flow

smorin · smorin · commit 4a9d71ee50ba · 2026-02-16T11:23:41.000-08:00
diff --git a/Makefile b/Makefile
@@ -172,8 +172,11 @@ check-security: check-tools-security ## Security/dependency checks
 	typos
 
 .PHONY: check-release
-check-release: check-core ## Release readiness checks
+check-release: ## Release readiness checks
+	ENVGEN_HINTS=0 $(MAKE) check-core
 	cargo publish --dry-run --locked --allow-dirty
+	@python3 $(VERSION_BUMP_SCRIPT) status | awk -F= '/^crate_version=/{print "✓ Release readiness checks passed for crate v"$$2}'
+	@python3 $(VERSION_BUMP_SCRIPT) next-step --stage crate-after-check-release
 
 .PHONY: install
 install: ## Install envgen to ~/.cargo/bin
@@ -245,6 +248,7 @@ check-yaml-fixtures: yaml-lint-fixtures yaml-fmt-check-fixtures ## Lint + format
 
 check-schema: check-schema-biome check-schema-meta ## Validate the JSON Schema file (all layers)
 	@echo "✓ Schema passed all checks"
+	@python3 $(VERSION_BUMP_SCRIPT) next-step --stage schema-after-check-schema
 
 check-schema-biome: ## Layer 1: JSON lint/format check (Biome)
 	@echo "Checking schema formatting and linting (Biome)... (first run may download the tool)"
diff --git a/RELEASING.md b/RELEASING.md
@@ -54,6 +54,71 @@ This mapping must match the publish job in `.github/workflows/release.yml` exact
 - `make tag-schema`
 - `make push-tag-schema`
 
+## Guided hints
+
+Release-flow commands print a `Hint:` + `Next:` block to guide the next command in the sequence.
+
+- Default behavior:
+  - Hints are shown for local interactive runs (TTY).
+  - Hints are suppressed in CI/non-interactive output.
+- Override behavior:
+  - `ENVGEN_HINTS=1` forces hints on.
+  - `ENVGEN_HINTS=0` forces hints off.
+
+Commands with guided next-step output include:
+
+- `make bump-crate*`
+- `make check-release`
+- `make tag-crate`
+- `make push-tag-crate`
+- `make bump-schema*`
+- `make check-schema`
+- `make tag-schema`
+- `make push-tag-schema`
+
+Example (crate flow):
+
+```text
+$ make bump-crate-patch
+...
+Hint: Crate release prep updated to vX.Y.Z.
+Next:
+  $ make check-release
+```
+
+```text
+$ make check-release
+...
+✓ Release readiness checks passed for crate vX.Y.Z
+Hint: Release readiness checks passed for crate vX.Y.Z.
+Next:
+  $ git add Cargo.toml Cargo.lock CHANGELOG.md
+  $ git commit -m "chore(release): bump crate to vX.Y.Z"
+  $ git push origin main
+  $ make tag-crate
+```
+
+Example (schema flow):
+
+```text
+$ make bump-schema-patch
+...
+Hint: Schema release prep updated to vA.B.C.
+Next:
+  $ make check-schema
+```
+
+```text
+$ make check-schema
+...
+Hint: Schema checks passed for artifact vA.B.C.
+Next:
+  $ git add SCHEMA_VERSION SCHEMA_CHANGELOG.md schemas/envgen.schema.vA.B.C.json
+  $ git commit -m "chore(schema): schema-vA.B.C"
+  $ git push origin main
+  $ make tag-schema
+```
+
 ## Quality gate matrix
 
 | Entry point | Canonical target | Purpose |
diff --git a/scripts/version_bump.py b/scripts/version_bump.py
@@ -37,6 +37,24 @@
     "Compatibility",
 ]
 
+TRUTHY_ENV_VALUES = {"1", "true", "yes", "on"}
+FALSY_ENV_VALUES = {"", "0", "false", "no", "off"}
+
+NEXT_STEP_STAGES = (
+    "crate-after-bump",
+    "crate-after-check-release",
+    "crate-after-tag",
+    "crate-after-push-tag",
+    "schema-after-bump",
+    "schema-after-check-schema",
+    "schema-after-tag",
+    "schema-after-push-tag",
+)
+
+RELEASE_WORKFLOW_URL = (
+    "https://github.com/smorinlabs/envgen/actions/workflows/release.yml"
+)
+
 
 class BumpError(RuntimeError):
     """Raised when the bump flow should fail with a user-facing error."""
@@ -46,6 +64,145 @@ def fail(message: str) -> None:
     raise BumpError(message)
 
 
+def env_var_truthy(name: str) -> bool:
+    value = os.environ.get(name)
+    if value is None:
+        return False
+    return value.strip().lower() not in FALSY_ENV_VALUES
+
+
+def parse_hint_override() -> bool | None:
+    value = os.environ.get("ENVGEN_HINTS")
+    if value is None:
+        return None
+
+    normalized = value.strip().lower()
+    if normalized in TRUTHY_ENV_VALUES:
+        return True
+    if normalized in FALSY_ENV_VALUES:
+        return False
+    return None
+
+
+def hints_enabled() -> bool:
+    override = parse_hint_override()
+    if override is not None:
+        return override
+    if env_var_truthy("CI"):
+        return False
+    return sys.stdout.isatty()
+
+
+def render_next_step(
+    stage: str,
+    *,
+    crate_version: str | None = None,
+    schema_version: str | None = None,
+    tag_name: str | None = None,
+) -> tuple[str, list[str]]:
+    if stage == "crate-after-bump":
+        resolved_crate_version = crate_version or read_cargo_version()
+        return (
+            f"Crate release prep updated to v{resolved_crate_version}.",
+            ["$ make check-release"],
+        )
+
+    if stage == "crate-after-check-release":
+        resolved_crate_version = crate_version or read_cargo_version()
+        return (
+            f"Release readiness checks passed for crate v{resolved_crate_version}.",
+            [
+                "$ git add Cargo.toml Cargo.lock CHANGELOG.md",
+                f'$ git commit -m "chore(release): bump crate to v{resolved_crate_version}"',
+                "$ git push origin main",
+                "$ make tag-crate",
+            ],
+        )
+
+    if stage == "crate-after-tag":
+        resolved_crate_version = crate_version or read_cargo_version()
+        resolved_tag_name = tag_name or f"v{resolved_crate_version}"
+        return (
+            f"Local crate tag created: {resolved_tag_name}.",
+            ["$ make push-tag-crate"],
+        )
+
+    if stage == "crate-after-push-tag":
+        resolved_crate_version = crate_version or read_cargo_version()
+        resolved_tag_name = tag_name or f"v{resolved_crate_version}"
+        return (
+            f"Crate tag pushed to origin: {resolved_tag_name}.",
+            [
+                "Release workflow should trigger automatically from this tag push.",
+                f"Monitor: {RELEASE_WORKFLOW_URL}",
+            ],
+        )
+
+    if stage == "schema-after-bump":
+        resolved_schema_version = schema_version or read_schema_version_file()
+        return (
+            f"Schema release prep updated to v{resolved_schema_version}.",
+            ["$ make check-schema"],
+        )
+
+    if stage == "schema-after-check-schema":
+        resolved_schema_version = schema_version or read_schema_version_file()
+        schema_file = f"schemas/envgen.schema.v{resolved_schema_version}.json"
+        return (
+            f"Schema checks passed for artifact v{resolved_schema_version}.",
+            [
+                f"$ git add SCHEMA_VERSION SCHEMA_CHANGELOG.md {schema_file}",
+                f'$ git commit -m "chore(schema): schema-v{resolved_schema_version}"',
+                "$ git push origin main",
+                "$ make tag-schema",
+            ],
+        )
+
+    if stage == "schema-after-tag":
+        resolved_schema_version = schema_version or read_schema_version_file()
+        resolved_tag_name = tag_name or f"schema-v{resolved_schema_version}"
+        return (
+            f"Local schema tag created: {resolved_tag_name}.",
+            ["$ make push-tag-schema"],
+        )
+
+    if stage == "schema-after-push-tag":
+        resolved_schema_version = schema_version or read_schema_version_file()
+        resolved_tag_name = tag_name or f"schema-v{resolved_schema_version}"
+        return (
+            f"Schema tag pushed to origin: {resolved_tag_name}.",
+            [
+                "Schema tag pushes do not trigger crates.io publishing.",
+                "Create and push a crate tag (vX.Y.Z) when you want a crate release.",
+            ],
+        )
+
+    fail(f"Unsupported next-step stage: {stage}")
+
+
+def emit_next_step(
+    stage: str,
+    *,
+    crate_version: str | None = None,
+    schema_version: str | None = None,
+    tag_name: str | None = None,
+) -> None:
+    if not hints_enabled():
+        return
+
+    summary, lines = render_next_step(
+        stage,
+        crate_version=crate_version,
+        schema_version=schema_version,
+        tag_name=tag_name,
+    )
+    print("")
+    print(f"Hint: {summary}")
+    print("Next:")
+    for line in lines:
+        print(f"  {line}")
+
+
 def write_atomic(path: Path, content: str) -> None:
     tmp_path = path.with_suffix(path.suffix + ".tmp")
     tmp_path.write_text(content, encoding="utf-8")
@@ -344,6 +501,7 @@ def do_bump_crate(args: argparse.Namespace) -> None:
     print(f"crate version: {old} -> {new}")
     print(f"updated: {CARGO_TOML}")
     print(f"updated: {CHANGELOG}")
+    emit_next_step("crate-after-bump", crate_version=new)
 
 
 def do_bump_schema(args: argparse.Namespace) -> None:
@@ -386,34 +544,43 @@ def do_bump_schema(args: argparse.Namespace) -> None:
     print(f"updated: {SCHEMA_VERSION_FILE}")
     print(f"updated: {SCHEMA_CHANGELOG}")
     print(f"renamed: {old_schema_path} -> {new_schema_path}")
+    emit_next_step("schema-after-bump", schema_version=new)
 
 
 def do_tag_crate(args: argparse.Namespace) -> None:
     version = resolve_tag_crate_version(require_release_section=True)
     tag_name = f"v{version}"
     create_tag(tag_name, f"release {tag_name}", args.dry_run)
     print(f"created local tag: {tag_name}")
+    emit_next_step("crate-after-tag", crate_version=version, tag_name=tag_name)
 
 
 def do_push_tag_crate(args: argparse.Namespace) -> None:
     version = resolve_tag_crate_version(require_release_section=False)
     tag_name = f"v{version}"
     push_tag(tag_name, args.dry_run)
     print(f"pushed tag: {tag_name}")
+    emit_next_step("crate-after-push-tag", crate_version=version, tag_name=tag_name)
 
 
 def do_tag_schema(args: argparse.Namespace) -> None:
     version = resolve_tag_schema_version(require_release_section=True)
     tag_name = f"schema-v{version}"
     create_tag(tag_name, f"schema release {tag_name}", args.dry_run)
     print(f"created local tag: {tag_name}")
+    emit_next_step("schema-after-tag", schema_version=version, tag_name=tag_name)
 
 
 def do_push_tag_schema(args: argparse.Namespace) -> None:
     version = resolve_tag_schema_version(require_release_section=False)
     tag_name = f"schema-v{version}"
     push_tag(tag_name, args.dry_run)
     print(f"pushed tag: {tag_name}")
+    emit_next_step("schema-after-push-tag", schema_version=version, tag_name=tag_name)
+
+
+def do_next_step(args: argparse.Namespace) -> None:
+    emit_next_step(args.stage)
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -423,6 +590,13 @@ def build_parser() -> argparse.ArgumentParser:
     status = subparsers.add_parser("status", help="Show current crate/schema versions")
     status.set_defaults(func=do_status)
 
+    next_step = subparsers.add_parser(
+        "next-step",
+        help="Print guided next-step release hints for a flow stage",
+    )
+    next_step.add_argument("--stage", required=True, choices=NEXT_STEP_STAGES)
+    next_step.set_defaults(func=do_next_step)
+
     bump_crate = subparsers.add_parser("bump-crate", help="Bump crate version + CHANGELOG")
     bump_crate.add_argument("--level", choices=["patch", "minor", "major"])
     bump_crate.add_argument("--version")
