docs: implicit environments proposal

[lwshang]

No description provided.

[raymondk]

Could we achieve the same thing by having an implicit "ic" environment?

At the moment we have:

• implicit local network
• implicit mainnet network
• implicit local environment

If we add an implicit "ic" environment, then for simple cases you would be able to do:

# deploy to local
icp deploy

# deploy to mainnet
icp deploy --ic

ic environment and mainnet would not be overridable and are implicitly linked. So a basic configuration would only have the canister definition (everything else is implicit) and you don't need to worry about defining environment unless you want to deploy to different environments on the same network.

[lwshang]

One minor problem is the inconsistency of names:

• For "local", the network and the environment are the same name.
• For "mainnet", the implicit environment has a different name ic.

---

The major benefit of my proposal is that "New users don't need to learn environments immediately".

An ICP beginner probably just wants to "deploy my canister to the mainnet". Then they can intuitively run icp deploy --network mainnet. There is no concept of environment at this point.

Another benefit of my proposal is less implicit definitions. We will only have the networks "local" and "mainnet" being implicit. The corresponding default environments are available but not some extra implicit definitions. Every network has a implicit environment.

[raymondk]

I'm not sure that an environment is that complicated of a concept to grasp even for a beginner: It's pretty common as a dev concept.

I agree however that having to write configuration in order to deploy to mainnet is annoying. eg:

❯ icp deploy --ic
Error: project does not contain an environment named 'ic'

If the ic environment is implicit does make things easier.

It seems more confusing to me to have to think of an environment later and to be able to pass both a network and an environment like you have line#70

[raymondk]

Maybe what would make sense to me is:

• When you define a network there is an implied environment with the same name using that network.
• There are always local and mainnet networks
• You can override the definition of local (you might have to override the definition of mainnet if you want to go through a specific boundary node 🤷 )
• You always have a local and mainnet environments because you always have local and mainnet networks
• You can define an environment with the same name as the network but then it must use that network.

This would mean that you can deploy to a network - and it would effectively be deploying to the environment with the same name. Or you can deploy to some environment.
And I think that this is more confusing than to say "you always deploy to an environment"

[lwshang]

I should have pointed out the major mental model shift much earlier.

---

The existing project manifest structure makes both network and environment top level items. An environment item must have one and only pointer to a network.

---

My new mental model is that the network is a top-level concept, under which environments can be optionally defined and configured. You need the(network_name, environment_name) pair to uniquely select an environment. When the environment_name part is omitted, the default implicit environment of that network is selected. There is no hidden connection like: the implied environment has the same name of the network.

For command like icp deploy, the complete form will be icp deploy --network XXX --environment YYY.
More accurately, icp deploy --network XXX should be interpreted as "deploy to the default environment of the network XXX".

It will be valid to define environment with the same name for different networks.
All the following commands can be valid in one project.

icp deploy --network local
icp deploy --network mainnet
icp deploy --network mainnet --environment staging
icp deploy --network testnet
icp deploy --network testnet --environment staging

The --network and --environment CLI options can be handled more consistently:

• For commands that takes --environment (e.g. icp deploy), both --network and --environment can be set at the same time.
• For commands that takes only --network (e.g., icp network start), setting --environment is not allowed anymore.

P.S. Too much typing is a pain; the short argument is the cure: icp deploy -n testnet -e staging

[raymondk]

How is the default environment for that network specified?

[lwshang]

Each network will have an implicit default environment. This applies to the implicit networks (local and mainnet) and explicit networks (e.g. testnet).
If only --network <NAME> is specified, the implicit default environment of that network will be the target.

[raymondk]

The environment allows you to override canister settings.
If there is an implicit environment for each network, how do you override canister settings in the network's default environment?

[lwshang]

Default environments are implicit, but they remain fully customizable—much like how we configure the implicit 'local' network.
I’ll update the design doc with a more complex manifest example to clarify this.