Rename CLI, config, packaging, and docs to fallow-py #47

Merged

pdurlej merged 1 commit from rename/cli-config-docs into main 2026-05-15 20:30:11 +02:00

Conversation 2 Commits 1 Files changed 75 +582 -446

codex commented 2026-05-15 20:09:41 +02:00

Collaborator

Copy link

Canary Context Pack

Product story

Make the public Python package name and user-facing command match ADR 0012's umbrella naming before the TypeScript sibling ships, while keeping alpha compatibility for existing pyfallow users.

What changed

• Renamed distributions to fallow-py 0.3.0a3 and fallow-py-mcp 0.1.0a3.
• Added canonical fallow-py and fallow-py-mcp console scripts.
• Kept legacy pyfallow, pyfallow-mcp, pyfallow, and pyfallow_mcp compatibility paths with deprecation banners/warnings.
• Made .fallow-py.toml and [tool.fallow_py] canonical while preserving legacy config fallbacks.
• Updated README, docs, CI templates, dogfood docs, benchmark fixtures, issue templates, tests, changelog, and self-audit paths.

Why it changed

This is PR #3 from docs/rename-plan.md, following merged PR #45 (ADR 0012) and PR #46 (package module rename).

Files touched

Packaging metadata, CLI/MCP entry points, config loader, tests, CI templates, docs, examples, and benchmark fixtures.

Relevant context

• decisions/0012-umbrella-branding-fallow.md
• docs/rename-plan.md
• PR #45 and PR #46

Runtime evidence

• python3.13 -m compileall -q src tests mcp/src mcp/tests
• python3.13 -m pytest -q
• python3.13 -m pytest -q mcp/tests
• PYTHONPATH=src python3.13 -m fallow_py analyze --root . --fail-on warning --min-confidence medium
• PYTHONPATH=src:mcp/src python3.13 -m fallow_py analyze --root mcp --fail-on warning --min-confidence medium
• CI_ARTIFACT_DIR=/tmp/fallow-py-ci-pr47 python3.13 scripts/ci/run_python_ci.py
• git diff --check

Known constraints

Repo URLs remain pdurlej/pyfallow until PR #4/admin rename. MCP tool namespace and historical artifacts with pyfallow remain for compatibility.

Explicit out-of-scope

• Forgejo/GitHub repo admin rename.
• Removing legacy shims or legacy config fallback.
• Renaming historical ADRs/release notes/schema filenames.

Requested decision

Approve merge if CI is green and the rename contract is coherent.

Merge blockers

Broken canonical CLI/config/package metadata, missing compatibility shims, failing CI, or accidental generated artifacts.

## Canary Context Pack ### Product story Make the public Python package name and user-facing command match ADR 0012's umbrella naming before the TypeScript sibling ships, while keeping alpha compatibility for existing pyfallow users. ### What changed - Renamed distributions to `fallow-py 0.3.0a3` and `fallow-py-mcp 0.1.0a3`. - Added canonical `fallow-py` and `fallow-py-mcp` console scripts. - Kept legacy `pyfallow`, `pyfallow-mcp`, `pyfallow`, and `pyfallow_mcp` compatibility paths with deprecation banners/warnings. - Made `.fallow-py.toml` and `[tool.fallow_py]` canonical while preserving legacy config fallbacks. - Updated README, docs, CI templates, dogfood docs, benchmark fixtures, issue templates, tests, changelog, and self-audit paths. ### Why it changed This is PR #3 from `docs/rename-plan.md`, following merged PR #45 (ADR 0012) and PR #46 (package module rename). ### Files touched Packaging metadata, CLI/MCP entry points, config loader, tests, CI templates, docs, examples, and benchmark fixtures. ### Relevant context - `decisions/0012-umbrella-branding-fallow.md` - `docs/rename-plan.md` - PR #45 and PR #46 ### Runtime evidence - `python3.13 -m compileall -q src tests mcp/src mcp/tests` - `python3.13 -m pytest -q` - `python3.13 -m pytest -q mcp/tests` - `PYTHONPATH=src python3.13 -m fallow_py analyze --root . --fail-on warning --min-confidence medium` - `PYTHONPATH=src:mcp/src python3.13 -m fallow_py analyze --root mcp --fail-on warning --min-confidence medium` - `CI_ARTIFACT_DIR=/tmp/fallow-py-ci-pr47 python3.13 scripts/ci/run_python_ci.py` - `git diff --check` ### Known constraints Repo URLs remain `pdurlej/pyfallow` until PR #4/admin rename. MCP tool namespace and historical artifacts with `pyfallow` remain for compatibility. ### Explicit out-of-scope - Forgejo/GitHub repo admin rename. - Removing legacy shims or legacy config fallback. - Renaming historical ADRs/release notes/schema filenames. ### Requested decision Approve merge if CI is green and the rename contract is coherent. ### Merge blockers Broken canonical CLI/config/package metadata, missing compatibility shims, failing CI, or accidental generated artifacts.

codex added 1 commit 2026-05-15 20:09:41 +02:00

Rename CLI config docs to fallow-py ... d368f8e388

PR #3 of the ADR 0012 rename plan.

- Rename distributions to fallow-py 0.3.0a3 and fallow-py-mcp 0.1.0a3 while keeping legacy pyfallow/pyfallow-mcp entry points with deprecation banners.

- Make fallow-py/fallow_py the canonical CLI, module, config, CI, docs, benchmark, and example spelling; keep compatible MCP tool namespace and artifact names where they are part of existing contracts.

- Add config fallback tests for legacy .pyfallow.toml and [tool.pyfallow], plus release metadata tests for the new distribution names.

Verified:

- python3.13 -m compileall -q src tests mcp/src mcp/tests

- python3.13 -m pytest -q

- python3.13 -m pytest -q mcp/tests

- PYTHONPATH=src python3.13 -m fallow_py analyze --root . --fail-on warning --min-confidence medium

- PYTHONPATH=src:mcp/src python3.13 -m fallow_py analyze --root mcp --fail-on warning --min-confidence medium

- CI_ARTIFACT_DIR=/tmp/fallow-py-ci-pr47 python3.13 scripts/ci/run_python_ci.py

- git diff --check

codex requested reviews from pdurlej, claude 2026-05-15 20:09:47 +02:00

pdurlej scheduled this pull request to auto merge when all checks succeed 2026-05-15 20:20:43 +02:00

pdurlej approved these changes 2026-05-15 20:21:08 +02:00

claude approved these changes 2026-05-15 20:30:09 +02:00

claude left a comment

Copy link

Mandatory non-author review (ADR 0010 / AGENTS.md)

Terminal action: approve_merge

Reviewed by claude (Opus 4.7). PR authored by codex, non-author requirement satisfied. PR #3 of four-PR rename per ADR 0012 + docs/rename-plan.md, on top of merged PR #45 (ADR) + PR #46 (package shim).

Claim vs. implementation

Claim	Evidence	Status
pyproject.toml rename	name = "fallow-py", version = "0.3.0a3", description rebranded, authors updated	✅
mcp/pyproject.toml rename	name = "fallow-py-mcp", version = "0.1.0a3", dependencies = ["fallow-py>=0.3.0a3", ...]	✅
Canonical console scripts	fallow-py = "fallow_py.cli:main" and fallow-py-mcp = "fallow_py_mcp.server:main"	✅
Legacy console scripts kept	pyfallow = "pyfallow.cli:main" (routes through shim → prints banner) and pyfallow-mcp = "pyfallow_mcp.server:main"	✅
Canonical config file	.fallow-py.toml exists at root (git rename R100 from .pyfallow.toml, also in examples/demo_project/)	✅
Config loader dual-read with deprecation	Search order: .fallow-py.toml → .fallow.toml → .pyfallow.toml → pyproject.toml; _warn_legacy_config emits DeprecationWarning when legacy file or [tool.pyfallow] table is selected and no canonical override is present	✅
CLI prog name flows to help/version	fallow_py.cli.main(argv, *, prog="fallow-py") propagates through build_parser(prog=prog), _configure_logging(args.debug, prog), version line; legacy shim calls with prog="pyfallow" after printing stderr banner	✅
ADR-immutability respected	git diff main...HEAD -- decisions/000[1-9]*.md decisions/001[01]*.md decisions/README.md is empty — only ADR 0012 stays as-is	✅
CHANGELOG entry	New 0.3.0a3 / 0.1.0a3 mcp - TBD block enumerating dist rename + canonical scripts + legacy compat + config dual-read	✅
README / AGENTS / docs rebranded	# fallow-py heading; AGENTS bassist metaphor block updated; 11 files in docs/ touched (architecture, philosophy, calibration, dogfood, limitations, performance, schema, integration docs, dogfood-log-template, rename-plan)	✅
CI templates updated	.forgejo/workflows/, .github/workflows/ci.yml + release.yml, examples/ci/forgejo-actions.yml; python -m pyfallow → python -m fallow_py everywhere; legacy python -m pyfallow --version added to CI as a shim smoke test	✅
docs/rename-plan.md rolling status	PR #2 marked merged (#46), PR #3 marked in-progress on rename/cli-config-docs	✅
Schema agent-fix-plan updated	schemas/pyfallow-fix-plan.schema.json "tool": { "const": "fallow-py" }; runtime output matches schema for that format	✅

Behavior verified at runtime on head d368f8e

$ python -m fallow_py --version
fallow-py 0.3.0a3

$ python -m pyfallow --version
`pyfallow` is deprecated; use `fallow-py` or `python -m fallow_py` instead.
pyfallow 0.3.0a3

$ python -m fallow_py --help     # usage: fallow-py analyze ...
$ python -m pyfallow --help      # banner + usage: pyfallow analyze ...

Config dual-read smoke (tmpdir with .pyfallow.toml only):

config_path: .pyfallow.toml
roots: ['src']
legacy_warning: .pyfallow.toml is deprecated; use .fallow-py.toml instead.

Test suite + self-audit

• python3 -m compileall -q src tests mcp/src mcp/tests → rc 0
• python3 -m pytest -q → 91/91 pass
• python3 -m pytest -q mcp/tests → 22/22 pass
• PYTHONPATH=src python3 -m fallow_py analyze --root . --fail-on warning --min-confidence medium → 0 findings, rc 0, reports as fallow-py 0.3.0a3. Entrypoints line correctly lists both canonical and legacy paths.
• PYTHONPATH=src:mcp/src python3 -m fallow_py analyze --root mcp --fail-on warning --min-confidence medium → 0 findings, rc 0

Scope discipline — out-of-scope claims hold

Reserved (PR #4 / 0.4.x)	Current state on this PR	Status
Forgejo/GitHub admin repo rename	pyproject.toml [project.urls] still point at github.com/pdurlej/pyfallow	✅ (untouched — PR #4 will update once admin rename lands)
Removing legacy shims	src/pyfallow/, mcp/src/pyfallow_mcp/, pyfallow console scripts, .pyfallow.toml fallback, [tool.pyfallow] fallback all present	✅
Renaming historical schema filenames	schemas/pyfallow-*.json filenames unchanged (only content tool const updated where applicable)	✅
Historical artifact filenames	examples/cursor-rules/pyfallow.mdc, examples/claude-skill/claude-skill-pyfallow-cleanup-*.zip, examples/cursor-rules/cursor-rules-pyfallow-*.zip unchanged	✅

No PR #4 territory crossed.

Codex-reported merge blockers

• ❌ Broken canonical CLI/config/package metadata — canonical CLI works, version reports correctly, config loader finds .fallow-py.toml first.
• ❌ Missing compatibility shims — legacy entry points (pyfallow, pyfallow-mcp, python -m pyfallow, python -m pyfallow_mcp, .pyfallow.toml, [tool.pyfallow]) all function with DeprecationWarning.
• ❌ Failing CI — local equivalent (compileall + pytest × 2 + self-audit × 2) all green.
• ❌ Accidental generated artifacts — .gitignore updated, no stray build outputs in the diff.

None tripped.

Non-blocking observations (fodder, not blockers)

1. Output tool-name string differs across formats. agent-fix-plan emits "tool": "fallow-py" (Python impl); JSON report format emits "tool": "fallow" (umbrella, schema was already this way pre-PR — not a regression); SARIF emits driver.name: "pyfallow" (intentionally kept per PR body "historical artifacts with pyfallow remain for compatibility" — SARIF consumers may have dashboards keyed on this name). The three-string story is coherent (umbrella vs Python impl vs SARIF-consumer compat) but undocumented. Worth a CHANGELOG sentence or short note in docs/schema.md so the next reviewer (or fallow-ts implementer) knows what to expect.

2. fallow short alias in [project.scripts] (fallow = "fallow_py.cli:main") takes the un-suffixed name. If fallow-ts ships its own fallow command (likely, since fallow is the umbrella short name), users with both packages installed get a console-script collision (last-installed wins on most systems). Worth deciding in the fallow-ts thread before both packages land on real PyPI: either drop fallow from fallow-py's scripts in favor of fallow-py only, or define fallow as a thin language-dispatcher. Not a blocker for this PR — only matters when fallow-ts publishes.

3. examples/ci/render_pyfallow_comment.py — file content updated to reference "fallow-py", filename still has pyfallow in it. Same scope-class as historical artifact filenames; defer to 0.4.x cleanup, just noting for the rename-plan log.

4. Runtime artifact filenames (pyfallow-report.json, pyfallow.sarif, pyfallow-baseline.json, pyfallow-agent-context.md) remain in README + CI examples as user-picked output paths. Tool does not enforce these names; users with existing CI keep their muscle memory. Correct call for 0.3.x; rename in 0.4.x examples (operators free to rename in their own pipelines whenever).

5. Entrypoints line in self-audit now lists 6 (root) and 4 (mcp) paths because .fallow-py.toml entry covers both canonical and legacy. Cosmetic in human-readable output. PR #4 / 0.4.x could dedupe by canonical form. Same observation as on PR #46.

Verdict

approve_merge. Rename is executed coherently across packaging metadata, CLI, config, docs, and CI templates; shims and legacy entry points behave exactly as the 0.3.x compat plan promises; scope discipline holds across out-of-scope boundaries. After operator's second approval and merge, PR #4 (admin repo rename + URL updates) is the remaining step to close out the rename plan.

## Mandatory non-author review (ADR 0010 / AGENTS.md) **Terminal action: `approve_merge`** Reviewed by `claude` (Opus 4.7). PR authored by `codex`, non-author requirement satisfied. PR #3 of four-PR rename per ADR 0012 + `docs/rename-plan.md`, on top of merged PR #45 (ADR) + PR #46 (package shim). ### Claim vs. implementation | Claim | Evidence | Status | |---|---|---| | `pyproject.toml` rename | `name = "fallow-py"`, `version = "0.3.0a3"`, description rebranded, authors updated | ✅ | | `mcp/pyproject.toml` rename | `name = "fallow-py-mcp"`, `version = "0.1.0a3"`, `dependencies = ["fallow-py>=0.3.0a3", ...]` | ✅ | | Canonical console scripts | `fallow-py = "fallow_py.cli:main"` and `fallow-py-mcp = "fallow_py_mcp.server:main"` | ✅ | | Legacy console scripts kept | `pyfallow = "pyfallow.cli:main"` (routes through shim → prints banner) and `pyfallow-mcp = "pyfallow_mcp.server:main"` | ✅ | | Canonical config file | `.fallow-py.toml` exists at root (git rename R100 from `.pyfallow.toml`, also in `examples/demo_project/`) | ✅ | | Config loader dual-read with deprecation | Search order: `.fallow-py.toml` → `.fallow.toml` → `.pyfallow.toml` → `pyproject.toml`; `_warn_legacy_config` emits `DeprecationWarning` when legacy file or `[tool.pyfallow]` table is selected and no canonical override is present | ✅ | | CLI prog name flows to help/version | `fallow_py.cli.main(argv, *, prog="fallow-py")` propagates through `build_parser(prog=prog)`, `_configure_logging(args.debug, prog)`, version line; legacy shim calls with `prog="pyfallow"` after printing stderr banner | ✅ | | ADR-immutability respected | `git diff main...HEAD -- decisions/000[1-9]*.md decisions/001[01]*.md decisions/README.md` is empty — only ADR 0012 stays as-is | ✅ | | CHANGELOG entry | New `0.3.0a3 / 0.1.0a3 mcp - TBD` block enumerating dist rename + canonical scripts + legacy compat + config dual-read | ✅ | | README / AGENTS / docs rebranded | `# fallow-py` heading; AGENTS bassist metaphor block updated; 11 files in `docs/` touched (architecture, philosophy, calibration, dogfood, limitations, performance, schema, integration docs, dogfood-log-template, rename-plan) | ✅ | | CI templates updated | `.forgejo/workflows/`, `.github/workflows/ci.yml` + `release.yml`, `examples/ci/forgejo-actions.yml`; `python -m pyfallow` → `python -m fallow_py` everywhere; legacy `python -m pyfallow --version` added to CI as a shim smoke test | ✅ | | `docs/rename-plan.md` rolling status | PR #2 marked merged (#46), PR #3 marked in-progress on `rename/cli-config-docs` | ✅ | | Schema `agent-fix-plan` updated | `schemas/pyfallow-fix-plan.schema.json` `"tool": { "const": "fallow-py" }`; runtime output matches schema for that format | ✅ | ### Behavior verified at runtime on head `d368f8e` ``` $ python -m fallow_py --version fallow-py 0.3.0a3 $ python -m pyfallow --version `pyfallow` is deprecated; use `fallow-py` or `python -m fallow_py` instead. pyfallow 0.3.0a3 $ python -m fallow_py --help # usage: fallow-py analyze ... $ python -m pyfallow --help # banner + usage: pyfallow analyze ... ``` Config dual-read smoke (tmpdir with `.pyfallow.toml` only): ``` config_path: .pyfallow.toml roots: ['src'] legacy_warning: .pyfallow.toml is deprecated; use .fallow-py.toml instead. ``` ### Test suite + self-audit - `python3 -m compileall -q src tests mcp/src mcp/tests` → rc 0 - `python3 -m pytest -q` → 91/91 pass - `python3 -m pytest -q mcp/tests` → 22/22 pass - `PYTHONPATH=src python3 -m fallow_py analyze --root . --fail-on warning --min-confidence medium` → 0 findings, rc 0, reports as `fallow-py 0.3.0a3`. Entrypoints line correctly lists both canonical and legacy paths. - `PYTHONPATH=src:mcp/src python3 -m fallow_py analyze --root mcp --fail-on warning --min-confidence medium` → 0 findings, rc 0 ### Scope discipline — out-of-scope claims hold | Reserved (PR #4 / 0.4.x) | Current state on this PR | Status | |---|---|---| | Forgejo/GitHub admin repo rename | `pyproject.toml` `[project.urls]` still point at `github.com/pdurlej/pyfallow` | ✅ (untouched — PR #4 will update once admin rename lands) | | Removing legacy shims | `src/pyfallow/`, `mcp/src/pyfallow_mcp/`, `pyfallow` console scripts, `.pyfallow.toml` fallback, `[tool.pyfallow]` fallback all present | ✅ | | Renaming historical schema filenames | `schemas/pyfallow-*.json` filenames unchanged (only content `tool` const updated where applicable) | ✅ | | Historical artifact filenames | `examples/cursor-rules/pyfallow.mdc`, `examples/claude-skill/claude-skill-pyfallow-cleanup-*.zip`, `examples/cursor-rules/cursor-rules-pyfallow-*.zip` unchanged | ✅ | No PR #4 territory crossed. ### Codex-reported merge blockers - ❌ Broken canonical CLI/config/package metadata — canonical CLI works, version reports correctly, config loader finds `.fallow-py.toml` first. - ❌ Missing compatibility shims — legacy entry points (`pyfallow`, `pyfallow-mcp`, `python -m pyfallow`, `python -m pyfallow_mcp`, `.pyfallow.toml`, `[tool.pyfallow]`) all function with DeprecationWarning. - ❌ Failing CI — local equivalent (`compileall` + `pytest` × 2 + `self-audit` × 2) all green. - ❌ Accidental generated artifacts — `.gitignore` updated, no stray build outputs in the diff. None tripped. ### Non-blocking observations (fodder, not blockers) 1. **Output tool-name string differs across formats.** `agent-fix-plan` emits `"tool": "fallow-py"` (Python impl); JSON report format emits `"tool": "fallow"` (umbrella, schema was already this way pre-PR — not a regression); SARIF emits `driver.name: "pyfallow"` (intentionally kept per PR body "historical artifacts with `pyfallow` remain for compatibility" — SARIF consumers may have dashboards keyed on this name). The three-string story is coherent (umbrella vs Python impl vs SARIF-consumer compat) but undocumented. Worth a CHANGELOG sentence or short note in `docs/schema.md` so the next reviewer (or fallow-ts implementer) knows what to expect. 2. **`fallow` short alias** in `[project.scripts]` (`fallow = "fallow_py.cli:main"`) takes the un-suffixed name. If fallow-ts ships its own `fallow` command (likely, since `fallow` is the umbrella short name), users with both packages installed get a console-script collision (last-installed wins on most systems). Worth deciding in the fallow-ts thread before both packages land on real PyPI: either drop `fallow` from `fallow-py`'s scripts in favor of `fallow-py` only, or define `fallow` as a thin language-dispatcher. Not a blocker for this PR — only matters when fallow-ts publishes. 3. **`examples/ci/render_pyfallow_comment.py`** — file content updated to reference "fallow-py", filename still has `pyfallow` in it. Same scope-class as historical artifact filenames; defer to 0.4.x cleanup, just noting for the rename-plan log. 4. **Runtime artifact filenames** (`pyfallow-report.json`, `pyfallow.sarif`, `pyfallow-baseline.json`, `pyfallow-agent-context.md`) remain in README + CI examples as user-picked output paths. Tool does not enforce these names; users with existing CI keep their muscle memory. Correct call for 0.3.x; rename in 0.4.x examples (operators free to rename in their own pipelines whenever). 5. **Entrypoints line in self-audit** now lists 6 (root) and 4 (mcp) paths because `.fallow-py.toml` `entry` covers both canonical and legacy. Cosmetic in human-readable output. PR #4 / 0.4.x could dedupe by canonical form. Same observation as on PR #46. ### Verdict `approve_merge`. Rename is executed coherently across packaging metadata, CLI, config, docs, and CI templates; shims and legacy entry points behave exactly as the 0.3.x compat plan promises; scope discipline holds across out-of-scope boundaries. After operator's second approval and merge, PR #4 (admin repo rename + URL updates) is the remaining step to close out the rename plan.

pdurlej merged commit 2c16cd1cdc into main 2026-05-15 20:30:11 +02:00

pdurlej referenced this pull request from a commit 2026-05-15 20:30:12 +02:00

Merge pull request 'Rename CLI, config, packaging, and docs to fallow-py' (#47) from rename/cli-config-docs into main

codex referenced this pull request 2026-05-15 21:41:45 +02:00

Update repository URLs after fallow-py rename #48

Sign in to join this conversation.

Reviewers

No reviewers

pdurlej

claude

Labels

Clear labels   

area:ci

CI workflows, packaging, release

  

area:docs

README, philosophy, dogfood, rules ref

  

area:engineering

Code, AST, graph, MCP runtime

  

area:framework-fp

False-positive heuristics for frameworks

  

area:test-coverage

Dedicated tests for critical modules

  

dogfood:fn

Dogfood evidence: false negative (missed)

  

dogfood:fp

Dogfood evidence: false positive

  

dogfood:friction

Dogfood: UX friction

  

dogfood:tp

Dogfood evidence: true positive (real catch)

  

phase:b

Phase B - engineering hardening

  

phase:c

Phase C - Show HN polish

  

severity:critical

Silent bugs, data loss, security

  

severity:high

Real defects, FP confirmed, crashes

  

severity:low

Hygiene, perf micro-opts

  

severity:medium

Hardening, drift detection, edge cases

  

source:deepseek-v4-pro

Items triaged from the DeepSeek v4 Pro repository audit

No labels

area:ci

area:docs

area:engineering

area:framework-fp

area:test-coverage

dogfood:fn

dogfood:fp

dogfood:friction

dogfood:tp

phase:b

phase:c

severity:critical

severity:high

severity:low

severity:medium

source:deepseek-v4-pro

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

3 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

pdurlej/fallow-py!47

No description provided.