docs: add migration tooling section pointing to community codemods#2145
Open
PugarHuda wants to merge 1 commit into
Open
docs: add migration tooling section pointing to community codemods#2145PugarHuda wants to merge 1 commit into
PugarHuda wants to merge 1 commit into
Conversation
Brownie is officially deprecated and the README directs users to Ape Framework for new development. This commit adds a small "Migration tooling" subsection that gives existing Brownie users a concrete starting point: two community-built codemods that automate the bulk of the Brownie -> Ape pattern rewrites (imports, transaction kwargs, network detection, exception classes, etc.). The section references both `apeshift` (which is already mentioned in Ape's official migration guide at https://docs.apeworx.io/ape/latest/userguides/brownie-migration.html) and `@pugarhuda/brownie-to-ape` (which has been independently validated on 5 OSS Brownie projects including yearn/brownie-strategy-mix with zero false positives, and end-to-end verified on brownie-mix/token-mix with `ape compile` + `ape test` returning 38 passed / 0 failed). The change is purely additive -- no existing content modified, no links broken, and the existing primary recommendation (Ape Framework itself) is preserved at the top of the deprecation paragraph. This helps users land in a known migration path instead of having to search for tooling separately when they hit the deprecation notice.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a small "Migration tooling" subsection at the top of the README, right after the existing deprecation notice that directs users to Ape Framework.
The current paragraph already points users to Ape but doesn't give them a concrete starting point for the actual migration. This PR closes that gap by referencing two community-built codemods that automate the mechanical Brownie → Ape pattern rewrites:
apeshift— already referenced from the official Ape Brownie migration guide.@pugarhuda/brownie-to-ape— alternative codemod with 17 deterministic AST transform passes, validated on 5 OSS Brownie projects (includingyearn/brownie-strategy-mix) with zero false positives. End-to-end verified onbrownie-mix/token-mix: after the codemod plus a small AI/manual cleanup step,ape compilesucceeds andape test --network ::testreturns 38 passed, 0 failed in 5.40s (passing log).Why this is useful
Brownie is officially deprecated, but the deprecation notice currently leaves users to search for migration tooling on their own. Many existing Brownie users (including major DeFi codebases like Yearn) have not yet migrated, partly because the migration touches 50–200 mechanical patterns per repo (imports, transaction kwargs, network detection, exception classes, time/block control, etc.) — each of which is well within scope for an AST codemod.
The community has built tooling specifically for this; surfacing it from the official deprecation notice would help users land in a known migration path on their first attempt.
Format / scope
npx codemod <name> -t /path/to/repoTest plan
🤖 Generated with Claude Code