Summary

Adds a comprehensive migration guide at docs/guides/migrations/brownie-to-ape.mdx for the Brownie → ApeWorx Ape upgrade, documenting the community-built @pugarhuda/brownie-to-ape codemod (source).

The format mirrors the recent React Router v6→v7 migration guide (#2167) — Steps, Before & After, CardGroup/Card components — and has been added to the existing Migrations group in docs/docs.json alongside react-18-19, nuxt-3-4, zod-3-4, msw-v1-v2, and pnpm-catalog.

Why this is useful

Brownie was the dominant Python framework for Ethereum smart-contract development from 2019, and was officially deprecated in 2023 in favor of ApeWorx Ape. Many public projects (including major DeFi codebases like Yearn Finance) still depend on it. Migrating a typical Brownie project means rewriting 50–200 mechanical patterns by hand:

• from brownie import … → from ape import … (with network → networks rename, constants moved to ape.utils)
• Contract.deploy({"from": x, "value": v}) → Contract.deploy(sender=x, value=v) — tx-dict to kwargs
• chain.sleep(60) → chain.pending_timestamp += 60 — different time-control semantics
• exceptions.VirtualMachineError → exceptions.ContractLogicError
• And ~12 more pattern categories

The @pugarhuda/brownie-to-ape codemod automates all of these via 17 deterministic AST transform passes (using ast-grep on Tree-sitter Python), with explicit FP guards. It's been validated on 5 real OSS Brownie projects (brownie-mix/token-mix, PatrickAlphaC/brownie_fund_me, PatrickAlphaC/smartcontract-lottery, PatrickAlphaC/aave_brownie_py_freecode, yearn/brownie-strategy-mix) with 0 false positives.

End-to-end verified: after the codemod plus ~30 LOC of AI/manual cleanup, ape compile succeeds (solc 0.6.12) and ape test --network ::test returns 38 passed, 0 failed in 5.40s on the migrated brownie-mix/token-mix. Full passing log: https://github.com/PugarHuda/brownie-to-ape/blob/main/docs/ape-verify-token-mix.log

What the guide covers

• 4-step migration flow (run codemod → migrate YAML config → AI/manual cleanup → verify)
• Table of all 17 transform passes with what each does
• Before/after code snippets for imports, tx kwargs, network detection, time/blocks, and exceptions
• Real-world validation table across 5 OSS repos
• Resource cards linking to GitHub repo, case study, live demo, and AI-step walkthrough

Format / conventions

• .mdx extension matches existing guides
• <Steps>, <Step>, <CardGroup>, <Card> components match react-router-v6-v7.mdx, react-18-19.mdx, nuxt-3-4.mdx
• Single-line frontmatter with title only
• Insertion in docs.json follows alphabetical/registry-version order of existing entries

Submission context

Submitted to the Codemod "Boring AI" hackathon (DoraHacks 2026, Tracks 1 + 2 + 3).

Test plan

• Markdown lint: file structure verified locally against react-router-v6-v7.mdx as reference
• All URLs in the guide resolve (codemod registry, GitHub source, ape-verify log, case study)
• docs.json JSON validity preserved (single line addition, no syntax change)
• No existing content modified
• No external dependencies added

🤖 Generated with Claude Code