docs: make target need for deploy command more explicit in successful clone message

[federicobozzini]

Changes

• Suggested by @ZachMaso. I agree the deploy suggestion can be more useful here and strengthen the user mental mode of how things are generally supposed to work.

[th3james]

This has been discussed before, I believe it is the wrong approach because it presumes that the user is using --target rather than the ENV var (or a config file, if we add one later). The challenge is that there isn't a "correct" API, but a number of options.
I think improvements to the error message when a command needs a target but one isn't specified would be higher leverage.

[federicobozzini]

I don't disagree but going through the experience of just following what we tell the users to do is quite painful. It's a loop of commands getting run and failing which might be quite discouraging. To me it feels like the environment variable is a convenience for advanced users that can be discovered later.

Not going to insist though, if you think this pushes us in the wrong direction I'll close the PR.

[ZachMaso]

After Clone could we say...

Now run:
cd topo-simd-visual-benchmark
topo deploy --target
OR or set TOPO_TARGET env var to avoid specifying target every time.

[muchzill4]

After Clone could we say...

Now run: cd topo-simd-visual-benchmark topo deploy --target OR or set TOPO_TARGET env var to avoid specifying target every time.

What if you already have TOPO_TARGET env variable? It feels redundant.

Ideal scenario is we know if invocation was w/ —target or target was sourced from the env and act accordingly.

[th3james]

I think "quite painful" is probably a bit hyperbolic. It's a command which (if the ENV is not specified) instantly fails and communicates what the user needs to do. If the user does have the ENV var specified, it's the correct command.

I agree we do need to help users build a mental model of how target selection works. The post-clone instructions should communicate that deployment requires a target, but presenting --target as part of the canonical invocation privileges one configuration mechanism and duplicates resolution guidance outside the command responsible for it.

Would this be an appropriate compromise?

Now run:
  cd <project>
  topo deploy

A deployment target is required. Provide --target or set TOPO_TARGET.

[ZachMaso]

I'd be quite happy with as james suggested

Now run:
cd
topo deploy

A deployment target is required. Provide --target or set TOPO_TARGET.

I just found it frustrating that if following instructions directly from AI portal you are essentially guaranteed to get an error. If we add this at least if they read all provided instructions they should avoid the error.

[federicobozzini]

Looks reasonable to me to, change made 2ea26ba