project deploy start is a confusing command, please split it up

[yippie]

Is your feature request related to a problem? Please describe.
The new project deploy start command has many issues and is a regression from the previous sfdx style commands. The new command is replacing three previously separate commands force:source:push, force:source:deploy, and force:mdapi:deploy. This causes a list of issues.

• force:source:deploy isn't actually replaced because source tracking is always done if possible, this means this command is effectively abandoned/lost (loss of functionality)
• Flags overload, there are 23 flags! Many of which are mutually exclusive
• Metadata API functions are clearly second class citizens with no shorthand single letter flag options for mdapi only flags
• If I have a Metadata API patch to distribute, suddenly the CLI is no longer an option to just deploy a simple zip file because the command is "project" and requires an sfdx-project even though deploying a metadata api zip file almost never has anything to do with an sfdx project. This makes creating a patch to give to a customer and tell them they can deploy with the CLI completely out of the question as they would need to create a fake project, and understand what that even means, to deploy the zip.
• When the default is to wait 33 min for the deploy, it is not "start" it is just a straight "deploy". The start feels unnecessary and not what I am doing most of the time.

What are you trying to do
Trying to deploy both source and metadata code to orgs in a way that is comprehensible to the user.

Sometimes source tracking in a project is not the answer. Source tracking gets messed up (like the source clear command demonstrate) or I have a test org I don't need source tracking or I have a patch I need to ensure gets applied. There is no way to ignore source tracking and force re-deploy a source folder. Changing to metadata api format is an option but that needlessly requires a project and an extra step and longer, clunkier flags.

Describe the solution you'd like
I propose a couple of changes:

• Create a completely separate command for Metadata API based operations that does not require an sfdx-project. This can then also have short hand flags for all of the mdapi flags
• Drop the "project". Deploying a whole project is only one of many use cases for deploying. Any time I am specifying --metadata-dir, -x, -m or even -d that is not a whole project and the project wording doesn't really make sense
• Drop the "start" or make it optional. 99% of the time I want to wait for the deploy (-w ) so it isn't start it is the complete deploy
• Either add a flag to turn source tracking off or split the concepts of push (w/tracking) vs deploy (no tracking) into separate commands

Describe alternatives you've considered
Staying with the abandoned SFDX commands that make much more sense.

[github-actions[bot]]

Thank you for filing this feature request. We appreciate your feedback and will review the feature at our next grooming or sprint planning session. We prioritize feature requests with more upvotes and comments.

[git2gus[bot]]

This issue has been linked to a new work item: W-13204464

[daveespo]

I agree with Kai's overall sentiment. The new command structure is byzantine and tries to hide the underlying Salesforce APIs beneath a layer of abstraction that leaves some of the use cases that Kai raises particularly challenging to address.

In particular, "project deploy start" is really "project deploy" .. using the keyword "start" implies something async by default and it's a synchronous command. And if all of these commands require a project directory, why bother with the "project" keyword?

[mshanemc]

Thanks for the feedback. Here's some insight on the design.

force:source:deploy isn't actually replaced because source tracking is always done if possible, this means this command is effectively abandoned/lost (loss of functionality)

force:source:deploy was --tracksource=false by default, but you has to make it true if you want to not screw up tracking. Push/pull had no way to select what to push/pull. That was a footgun.

The current model is, "if you don't care about tracking (ex: you want to run apex tests in CI and then destroy the org), you can do --no-track-source when using org create scratch.

We're working on better docs for the replacement commands that go through the intended use.

Metadata API functions are clearly second class citizens with no shorthand single letter flag options for mdapi only flags

That's very intentional. When the CLI came out, the pattern was source:convert => mdapi:deploy and that sucked. A lot of people still do it due to inertia, but when we tell them they can deploy from source format, they're usually happy to change.

Users also didn't like having 3 ways to deploy stuff (and the inconsistencies... -x on source, -k on mdapi both mean manifest!). push does tracking but source:deploy will screw up tracking, mdapi by default won't wait, source does, etc.

I hadn't heard the "zip file patch" use case before.

If I have a Metadata API patch to distribute, suddenly the CLI is no longer an option to just deploy a simple zip file

That is unintentional and should be fixed soon. You should be able to deploy the zip file without a project.

Drop the "project". Deploying a whole project is only one of many use cases for deploying. Any time I am specifying --metadata-dir, -x, -m or even -d that is not a whole project and the project wording doesn't really make sense

Don't read project:deploy as "deploy the whole project." Anytime you're doing a non-mdapi deploy or retrieve, it's referencing the project and considers project-level things like sfdx-project.json for pkgDirs, default directory, the sourceApiVersion (well, unless you manifest has one), .forceignore, source tracking, replacements, etc.

We had a lot of discussion about the naming of this command, and concluded that 80+% of the time, people would be doing deployments related to their project. The mdapi stuff is definitely an exception. But we also didn't want to have 2 deploy commands and have people wondering which one to use when.

You're not the first person to not like start.

[gdman]

The current model is, "if you don't care about tracking (ex: you want to run apex tests in CI and then destroy the org), you can do --no-track-source when using org create scratch.

How would I go about not caring about tracking for sandboxes? As I understand it, I can enable Source Tracking in Developer/Pro sandboxes from a global setting in Production. Which I haven't done so far because it can't be disabled again. If I enable this setting, does that mean sf retrieve and deploy commands will use source tracking for all dev/dev pro sandboxes and I'll have no control over it?

Basically, I want to try out source tracking in sandboxes but if I enable it, it sounds like it's enabled everywhere and can't be disabled afterwards. If it doesn't work / doesn't work for every scenario / commands force use of source tracking - I'd be stuck with it.

I could be completely mis-understanding though. Usually, I'd just test and find out but the 'setting can't be disabled' thing hinders that.

[gdman]

Just to update - I now realise the setting can be enabled and disabled (I was mis-reading the settings page). However, the rest of the message still stands. It's a global switch therefore I assume tracking is either enabled everywhere or disabled everywhere. Therefore, does that mean there is no way to retrieves/deploys without using source tracking if that global setting is enabled?

[yippie]

The mdapi stuff is definitely an exception. But we also didn't want to have 2 deploy commands and have people wondering which one to use when.

Except you made it way MORE confusing with this one, overloaded, command than two separate commands. If I could actually use the same flags you might have a point, but I can't. Instead I have to us -d for source and --metadata-dir for mdapi. This is much, MUCH more confusing than the nicely named source and mdapi commands. You have doubled the amount of typing needed to deploy mdapi formated code and made it way harder to find. I have yet to have a single colleague figure out how to deploy something in metadata API format on their own.

[mshanemc]

The new command structure is byzantine and tries to hide the underlying Salesforce APIs beneath a layer of abstraction

using the keyword "start" implies something async by default

Interesting. The intent was to make it clear that it is an async operation on the server. You might be waiting for it (that's the default) but you have other options (--async followed by project deploy resume, or project deploy cancel) that you can do against the operation that you started.

[daveespo]

(I realize the ship has sailed here and start is here to stay so we can call this thread resolved)

I probably would've had project deploy be the "synchronous" version .. and if you want async, you use the start (which returns immediately) and then check in later with resume or cancel altogether with cancel

[mshanemc]

I agree that there are a LOT of flags because mdapi is smashed in there, and that start feels superfluous.

[mshanemc]

have made this a discussion because they have threads

[patmcclellan]

I'm trying to change over from sfdx to sf, but really can't figure out how to construct something that does this:
sfdx force:source:deploy -u myorgalias -p force-app/main/default/lwc/myLwc

[patmcclellan]

Thanks!

[patmcclellan]

Testing it. I get this: Warning: project deploy start is not a sf command.

[patmcclellan]

I had been using sfdx update and thought I was up-to-date. I installed the package from here. Now it works.

[patmcclellan]

I've been pushing LWC straight to production, but the sf command won't let me. testLevel of NoTestRun cannot be used in production organizations

[mshanemc]

we changed that based on feedback. #2105

should be in this week's RC. You could try it out now, I think, with sfdx update nightly (and then sfdx update stable to get back to normal).

[mshanemc]

I think the functionality requests here are covered.

you can get tracking-free deploy/retrieve for orgs that would normally support tracking by [create a scratch org with --no-track-source or use org disable tracking on any org`

mdapi deploy/retrieve don't need projects and the "distribute patches via zip" work fine

we got all the "needs project" stuff sorted thanks to all the feedback.

---

the "too many flags" and "no short char for mdapi format options" and naming arguments remain.

Having 3 commands that did the similar things but not quite was definitely a footgun and eliminating that was very intentional. Favoring source-format projects over mdapi is 100% intentional.