Improve dependency management documentation #556
Conversation
- Restructure to explain local vs network dependencies upfront - Add step-by-step dependency resolution explanation - Explain why proof-generating commands bypass cache - Document edition pinning use cases - Add V8 constructor requirement note for deploy
JoshuaBatty
requested review from
AleoAlexander,
d0cd,
mohammadfawaz and
vicsn
| ```bash | ||
| leo add credits.aleo | ||
| ``` | ||
| or | ||
| ``` | ||
| ```bash | ||
| leo add credits | ||
| ``` | ||
|
|
||
| If you are deploying to mainnet, you will need to specify mainnet imports using the `--network` flag as follows: | ||
|
|
||
| ``` | ||
| For mainnet programs, specify the network: | ||
| ```bash | ||
| leo add credits --network mainnet | ||
| ``` |
There was a problem hiding this comment.
I think it's best practice to always include the --network flag, even for Testnet.
There was a problem hiding this comment.
My instinct is to only show flags when they're necessary, since testnet is the default, leo add credits just works. Showing --network testnet everywhere might imply it's required when it's not. The mainnet example already demonstrates the flag exists for when you need it. Thoughts?
There was a problem hiding this comment.
Turns out this guide is old. leo add was changed so that one of the following is required:
<--local <LOCAL>|--network|--edition <EDITION>>For some reason, you can't specify the network here. I imagine that it uses either the environment variable, the .env file, or the CLI argument when you call leo build.
There was a problem hiding this comment.
You're correct, leo add now requires one of --local <LOCAL>, --network, or --edition <EDITION>. Thanks for catching that. I'll update the documentation to reflect this requirement.
There was a problem hiding this comment.
@AleoAlexander this should be ready for re-review when you have time. Thanks!
vicsn
left a comment
vicsn
left a comment
There was a problem hiding this comment.
I have a few questions but overall LGTM.
Would love a redesign to make it simpler to use for developers.
| } | ||
| ``` | ||
|
|
||
| Local dependencies are compiled from source whenever you build. They never require network access. |
There was a problem hiding this comment.
Will dependencies of the local dependency be fetched from the network?
There was a problem hiding this comment.
Yes, transitive dependencies are fetched based on their own location type. If your local dependency imports a network program, that gets fetched from the network. If it imports another local path, that's read from disk.
| - When a dependency upgrade would break your program | ||
| - When you want to avoid unexpected behavior changes | ||
|
|
||
| **Note:** Local dependencies don't have editions - they're always compiled from your current source code. |
There was a problem hiding this comment.
What happens when the local dependency also lives in the network?
In any case, it must have some edition right, either 0 if this is the first deployment or perhaps higher if it's already present?
Not sure if the edition is actually materially used for anything.
There was a problem hiding this comment.
If it's marked as local, Leo just compiles from source and ignores any network presence. Editions only come into play for network dependencies - they tell Leo which on-chain version to fetch. Local deps don't have editions because you're compiling your source, not fetching bytecode.
At deploy time, if the local dep hasn't been deployed yet it becomes edition 0. If it already exists on-chain, the deploy would fail (you'd need to upgrade instead).
Co-authored-by: Alexander Kim <alexander@aleo.org> Signed-off-by: Joshua Batty <joshpbatty@gmail.com>
Co-authored-by: Alexander Kim <alexander@aleo.org> Signed-off-by: Joshua Batty <joshpbatty@gmail.com>
Co-authored-by: Alexander Kim <alexander@aleo.org> Signed-off-by: Joshua Batty <joshpbatty@gmail.com>
Co-authored-by: Alexander Kim <alexander@aleo.org> Signed-off-by: Joshua Batty <joshpbatty@gmail.com>
Co-authored-by: Alexander Kim <alexander@aleo.org> Signed-off-by: Joshua Batty <joshpbatty@gmail.com>
Co-authored-by: Alexander Kim <alexander@aleo.org> Signed-off-by: Joshua Batty <joshpbatty@gmail.com>
Co-authored-by: Alexander Kim <alexander@aleo.org> Signed-off-by: Joshua Batty <joshpbatty@gmail.com>
Co-authored-by: Alexander Kim <alexander@aleo.org> Signed-off-by: Joshua Batty <joshpbatty@gmail.com>
Agreed. Once we have the lock file actually populated a lot of this complexity around edition pinning goes away. Leo would just auto-record resolved editions on first build, and developers wouldn't need to think about it unless they explicitly want to update. |
Structure Changes
Content Changes
execute,deploy,upgrade,synthesize) bypass cacheRendered
Motivation
This documentation update accompanies ProvableHQ/leo#29027 which improves edition handling for dependencies. The existing docs did not clearly explain the distinction between local and network dependencies, or why different commands handle caching differently. This should help clarify these concepts for users.