Skip to content

Latest commit

 

History

History
184 lines (130 loc) · 6.98 KB

migrating-to-v6.0.0.md

File metadata and controls

184 lines (130 loc) · 6.98 KB

Migrating to v6.0.0

Version v6.0.0 brings the plugin into the sf plugin v2 architecture, which offers significant improvements in performance, maintainability, and security. While the upgrade comes with benefits, it also introduces some new behaviors and potential breaking changes. Versions v5.x and below will no longer be maintained (no bug fixes, no new metadata support, no API version updates, and no new features).

New Behaviors

Breaking Changes

Installation Details

sfdx-git-delta v6.x follows a new release channel structure:

  • latest-rc: Contains the latest fixes and features that have passed automated testing, but still await customer validation.
  • latest: This channel has been validated by real-world usage and is stable for most users.
  • stable: Represents the last fully stable release, typically for versions with 50k+ downloads.

Note

If you’ve been installing the plugin using these channels and are not impacted by v6 breaking changes, this transition should be seamless.

# install latest-rc

sf plugins install sfdx-git-delta@latest-rc

# install latest

sf plugins install sfdx-git-delta@latest
# or
sf plugins install sfdx-git-delta

# install stable

sf plugins install sfdx-git-delta@stable

Legacy version installation

If you need more time to adapt to version v6.x, the previous v5.x version is still available via the stable channel (for now), the legacy channel and via v5.x version alias:

  • stable: Installs the recommended stable version (v5 version as of january 2025).
  • legacy: Installs the latest v5 version (and will stay on this version).
# install stable (recommended approach)

sf plugins install sfdx-git-delta@stable
# install a specific version (5.46.0 for example)

sf plugins install [email protected]
# install legacy

sf plugins install sfdx-git-delta@legacy

Details

Deprecated Parameters

Several "long" parameters have been deprecated and replaced by new ones to comply with sf design guidelines:

  • --ignore → --ignore-file (short -i)
  • --ignore-destructive → --ignore-destructive-file (short -D)
  • --include → --include-file (short -n)
  • --include-destructive → --include-destructive-file (short -N)
  • --output → --output-dir (short -o)
  • --repo → --repo-dir (short -r)
  • --source → --source-dir (short -s)

For now, the old parameters are still functional, but they will stop working in a future release. It is recommended to migrate to the new parameters as soon as possible.

Error Handling for File and Directory Parameters

Error handling for file and directory type parameters is now managed by the Salesforce CLI itself. The following parameters are affected by this change:

  • --ignore-file
  • --ignore-destructive-file
  • --include-file
  • --include-destructive-file
  • --output-dir
  • --repo-dir
  • --source-dir

Errors are now surfaced by the Salesforce CLI, which impacts both the standard output and JSON output.

sfdx/cli No Longer Supported

With the migration to the sf plugin v2 architecture, sfdx-git-delta v6+ is no longer compatible with the deprecated sfdx/cli. It now requires @salesforce/cli.

If you are still using sfdx/cli, please migrate to sf (v2) before upgrading to version 6.

Plugin Default Output

The default output format no longer displays JSON by default. Instead, it takes advantage of the new Salesforce CLI UX tools, such as spinners, to provide real-time feedback on plugin operations. Warnings and errors are also presented directly in the standard output.

To continue using JSON output, you must now pass the --json flag.

JSON Output Structure

The JSON output has been simplified by removing duplicated information and aligning it with the Salesforce CLI's built-in capabilities. Previously, the JSON output was encapsulated and included redundant information, such as:

Old JSON Structure

{
  "status": 0,
  "result": { 
    "success": true,
    "output-dir": "<same as input parameter>",
    "error": "<encountered errors>",
    "warnings": ["<warnings>"]
  },
  "warnings": [
  ]
}

New JSON Structure

{
  "status": 0,
  "result": {
    "output-dir": "<same as input parameter or default value>",
    "error": "<plugin encountered error>"
  },
  "warnings": ["<encountered warnings>"]
}

When errors arise due to file/directory issues or other sf CLI-level problems, the output will look like this:

{
  "name": "Error",
  "message": "<sf cli encountered error>",
  "exitCode": 1,
  "context": "SourceDeltaGenerate",
  "stack": "<stack>",
  "cause": "<cause>",
  "warnings": [],
  "code": "1",
  "status": 1,
  "commandName": "SourceDeltaGenerate"
}

Export esm instead of commonjs

The plugin now exports using ES modules (with no more CommonJS support and no esmInteroperability). Here’s is how to import the plugin:

import sgd from 'sfdx-git-delta'

API version format

Previously, the plugin accepted API versions using the -a or --api-version parameter in two formats:

  • Integer (e.g., 62)
  • Float (e.g., 62.0)

Now it uses the orgApiVersionFlag standard flag and only accept floats ending with .0 (e.g., 62.0) Providing an integer will result in an error:
"62 is not a valid API version. It should end in '.0' like '54.0'."

Setting LogLevel

Previously with sfdx/cli LogLevel was set using the --loglevel parameter. It is deprecated, you cannot set the loglevel this way anymore. Now with the salesforce/cli LogLevel is set with the SF_LOG_LEVEL environment variable