`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]

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]

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.

[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.

[mshanemc]

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