From 013ce693f57ec239de3f38bd927974764e1776dd Mon Sep 17 00:00:00 2001 From: James Estevez Date: Fri, 28 Jul 2023 16:24:23 -0700 Subject: [PATCH 1/3] ADR: Handling Migration from SFDX to SF CLI in CumulusCI Salesforce has announced the deprecation of SFDX (v7) and is now focusing on the newer SF CLI (v2). They've said that SF CLI (v2) is smart enough to understand all SFDX commands, as well as new SF commands. However, our web applications and other integrations depend on SFDX. SFDX is end-of-life, so we need to cut over and make some improvements by using the new, better features. This ADR proposes that we delegate backwards compatibility to the SF CLI. --- ...ration-from-sfdx-to-sf-cli-in-cumulusci.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 docs/adrs/0002-handling-migration-from-sfdx-to-sf-cli-in-cumulusci.md diff --git a/docs/adrs/0002-handling-migration-from-sfdx-to-sf-cli-in-cumulusci.md b/docs/adrs/0002-handling-migration-from-sfdx-to-sf-cli-in-cumulusci.md new file mode 100644 index 0000000000..9104ef71a6 --- /dev/null +++ b/docs/adrs/0002-handling-migration-from-sfdx-to-sf-cli-in-cumulusci.md @@ -0,0 +1,75 @@ +--- +date: 2023-07-28 +status: Accepted +author: "@jstvz" +--- + +# ADR 2: Handling Migration from SFDX to SF CLI in CumulusCI + +## Context and Problem Statement + +## Context + +Salesforce has announced the deprecation of SFDX (v7) and is now focusing on the newer SF CLI (v2). They've said that SF CLI (v2) is smart enough to understand all SFDX commands, as well as new SF commands. However, our web applications and other integrations depend on SFDX. SFDX is end-of-life, so we need to cut over and make some improvements by using the new, better features. + +## Decision + +### Considered Options + +1. **Run commands based on what the user has (SFDX or SF CLI):** + + - Good: Gives users still using SFDX more time to switch. + - Good: Gives us time to fully understand the new SF CLI. + - Bad: It would make our code more complex and might confuse users. + - Bad: It divides our attention between old and new versions. + +2. **Stop supporting SFDX right away:** + + - Good: Lets us focus on the new SF CLI and stop worrying about old code. + - Good: Speeds up our switch to the new CLI and helps us find and fix problems sooner. + - Bad: It could disrupt users' work if they're still using SFDX. + - Bad: There could be problems with the new SF CLI we don't know about yet. + +3. **Let SF CLI handle old SFDX commands:** + - Good: Reduces changes to our commands, making the switch smoother for users. + - Good: Lets us switch to the new CLI slowly, reducing risk of big issues. + - Bad: Delays the inevitable. If they drop deprecated commands without us noticing, it would break functionality for our users. + - Bad: Could delay us learning and using new features of the SF CLI. + +### Decision Outcome + +Here's how we plan to make this change: + +- **Maintain Backwards Compatibility:** Our priority is to ensure that all existing processes continue to function as expected. We will not modify the existing SFDX commands in our project until SF CLI announces the version in which these commands will be deprecated. + +- **Delegate maintaining backwards compatibility to the SF CLI:** We will continue using existing commands as written and rely on SF CLI to interpret these commands. We think this will make the change easier and less disruptive. + +- **Warn users that are on SFDX (v7) that they need to upgrade:** We'll check the installed version of the CLI and warn users that future versions of CumulusCI will drop support. + +- **Update our integration tests to include `stable-rc`:** We'll revisit PR #3558 to make sure all tasks that use the CLI are tested in our workflow, and that we're testing the weekly release candidate channel (`stable-rc`). + +- **Update the Falcon web applications to depend on SF as soon as practical:** We know we need to switch to SF CLI, and we want our Falcon web apps to benefit from its latest updates and features as soon as possible. We'll also install all necessary JIT plugins in the apps, so we don't have to install them over and over during builds. + +- **Update the SFDX Heroku buildpack to depend on SF as soon as practical:** Like the Falcon web applications, we want our [Heroku buildpack](https://github.com/SalesforceFoundation/simple-salesforce-dx-buildpack)to stay up-to-date with the latest SF CLI to get its performance and feature enhancements. Like the Falcon web applications, this includes installing all necessary JIT plugins for the buildpack. + +## Consequences + +- Keeping things working as they are will cause the least disruption. +- By delegating backwards compatibility to the SF CLI, we can avoid making substantial changes to our command structure until it's necessary. +- Updating Falcon web apps and the SFDX Heroku buildpack to use the SF CLI will help us stay ahead of the change and avoid a scramble as the CLI removes deprecated commands. +- Installing JIT plugins in the apps and buildpack will make builds more efficient and avoid problems during runtime. +- However, this decision does mean that we will need to monitor Salesforce's communications closely for announcements about command deprecations, to ensure that our commands continue to function as expected. + +## References + +- [List of JIT plugins in SF CLI](https://github.com/salesforcecli/cli/blob/486a157c3d448d699c129f884bb3ab706523002a/package.json#L71-L81) +- [Salesforce CLI sf (v2) announcement blog post](https://developer.salesforce.com/blogs/2023/07/salesforce-cli-sf-v2-is-here) +- [CLI Deprecation Policy](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_dev_cli_deprecation.htm) +- [Issue #3621](https://github.com/SFDO-Tooling/CumulusCI/issues/3621) + + From 850a8369ad95e866d4570b0dd94002a7737c585c Mon Sep 17 00:00:00 2001 From: James Estevez Date: Wed, 2 Aug 2023 11:20:33 -0700 Subject: [PATCH 2/3] Updated based on review comments --- ...ling-migration-from-sfdx-to-sf-cli-in-cumulusci.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/adrs/0002-handling-migration-from-sfdx-to-sf-cli-in-cumulusci.md b/docs/adrs/0002-handling-migration-from-sfdx-to-sf-cli-in-cumulusci.md index 9104ef71a6..ad05aeac2b 100644 --- a/docs/adrs/0002-handling-migration-from-sfdx-to-sf-cli-in-cumulusci.md +++ b/docs/adrs/0002-handling-migration-from-sfdx-to-sf-cli-in-cumulusci.md @@ -8,8 +8,6 @@ author: "@jstvz" ## Context and Problem Statement -## Context - Salesforce has announced the deprecation of SFDX (v7) and is now focusing on the newer SF CLI (v2). They've said that SF CLI (v2) is smart enough to understand all SFDX commands, as well as new SF commands. However, our web applications and other integrations depend on SFDX. SFDX is end-of-life, so we need to cut over and make some improvements by using the new, better features. ## Decision @@ -20,8 +18,7 @@ Salesforce has announced the deprecation of SFDX (v7) and is now focusing on the - Good: Gives users still using SFDX more time to switch. - Good: Gives us time to fully understand the new SF CLI. - - Bad: It would make our code more complex and might confuse users. - - Bad: It divides our attention between old and new versions. + - Bad: The variable presence of the `sf` CLI can lead to inconsistencies in available commands for users. This will increase code complexity and may cause different behavior depending on the CLI used. 2. **Stop supporting SFDX right away:** @@ -42,15 +39,15 @@ Here's how we plan to make this change: - **Maintain Backwards Compatibility:** Our priority is to ensure that all existing processes continue to function as expected. We will not modify the existing SFDX commands in our project until SF CLI announces the version in which these commands will be deprecated. -- **Delegate maintaining backwards compatibility to the SF CLI:** We will continue using existing commands as written and rely on SF CLI to interpret these commands. We think this will make the change easier and less disruptive. +- **Delegate maintaining backwards compatibility to the SF CLI:** We'll leave the existing commands, which invoke the `sfdx` alias from `@salesforce/cli` package, as is and rely on SF CLI to interpret these commands. We think this will make the change easier and less disruptive. - **Warn users that are on SFDX (v7) that they need to upgrade:** We'll check the installed version of the CLI and warn users that future versions of CumulusCI will drop support. - **Update our integration tests to include `stable-rc`:** We'll revisit PR #3558 to make sure all tasks that use the CLI are tested in our workflow, and that we're testing the weekly release candidate channel (`stable-rc`). -- **Update the Falcon web applications to depend on SF as soon as practical:** We know we need to switch to SF CLI, and we want our Falcon web apps to benefit from its latest updates and features as soon as possible. We'll also install all necessary JIT plugins in the apps, so we don't have to install them over and over during builds. +- **Update the Falcon web applications to depend on SF as soon as practical:** We know we need to switch to SF CLI, and we want our Falcon web apps to benefit from its latest updates and features as soon as possible. We'll also install all necessary JIT plugins in the apps, so we don't have to install them over and over during builds. The timing of this switch will primarily depend on the team's bandwidth for testing the dependency switch and ensuring the `sf` CLI and JIT plugins are available. -- **Update the SFDX Heroku buildpack to depend on SF as soon as practical:** Like the Falcon web applications, we want our [Heroku buildpack](https://github.com/SalesforceFoundation/simple-salesforce-dx-buildpack)to stay up-to-date with the latest SF CLI to get its performance and feature enhancements. Like the Falcon web applications, this includes installing all necessary JIT plugins for the buildpack. +- **Update the SFDX Heroku buildpack to depend on SF as soon as practical:** Like the Falcon web applications, we want our [Heroku buildpack](https://github.com/SalesforceFoundation/simple-salesforce-dx-buildpack) to stay up-to-date with the latest SF CLI to get its performance and feature enhancements. Like the Falcon web applications, this includes installing all necessary JIT plugins for the buildpack. The timing of this update will also be dependent on the team's capacity to carry out the necessary updates and testing. ## Consequences From 8664d509eb2f1dd41327b9a35fd72ada20d53d7d Mon Sep 17 00:00:00 2001 From: James Estevez Date: Tue, 5 Dec 2023 13:10:27 -0800 Subject: [PATCH 3/3] Revise ADR to adopt hard break Also, move to ADR 3 --- ...ration-from-sfdx-to-sf-cli-in-cumulusci.md | 72 ------------------- .../0003-switch-to-sf-cli-in-cumulusci.md | 67 +++++++++++++++++ 2 files changed, 67 insertions(+), 72 deletions(-) delete mode 100644 docs/adrs/0002-handling-migration-from-sfdx-to-sf-cli-in-cumulusci.md create mode 100644 docs/adrs/0003-switch-to-sf-cli-in-cumulusci.md diff --git a/docs/adrs/0002-handling-migration-from-sfdx-to-sf-cli-in-cumulusci.md b/docs/adrs/0002-handling-migration-from-sfdx-to-sf-cli-in-cumulusci.md deleted file mode 100644 index ad05aeac2b..0000000000 --- a/docs/adrs/0002-handling-migration-from-sfdx-to-sf-cli-in-cumulusci.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -date: 2023-07-28 -status: Accepted -author: "@jstvz" ---- - -# ADR 2: Handling Migration from SFDX to SF CLI in CumulusCI - -## Context and Problem Statement - -Salesforce has announced the deprecation of SFDX (v7) and is now focusing on the newer SF CLI (v2). They've said that SF CLI (v2) is smart enough to understand all SFDX commands, as well as new SF commands. However, our web applications and other integrations depend on SFDX. SFDX is end-of-life, so we need to cut over and make some improvements by using the new, better features. - -## Decision - -### Considered Options - -1. **Run commands based on what the user has (SFDX or SF CLI):** - - - Good: Gives users still using SFDX more time to switch. - - Good: Gives us time to fully understand the new SF CLI. - - Bad: The variable presence of the `sf` CLI can lead to inconsistencies in available commands for users. This will increase code complexity and may cause different behavior depending on the CLI used. - -2. **Stop supporting SFDX right away:** - - - Good: Lets us focus on the new SF CLI and stop worrying about old code. - - Good: Speeds up our switch to the new CLI and helps us find and fix problems sooner. - - Bad: It could disrupt users' work if they're still using SFDX. - - Bad: There could be problems with the new SF CLI we don't know about yet. - -3. **Let SF CLI handle old SFDX commands:** - - Good: Reduces changes to our commands, making the switch smoother for users. - - Good: Lets us switch to the new CLI slowly, reducing risk of big issues. - - Bad: Delays the inevitable. If they drop deprecated commands without us noticing, it would break functionality for our users. - - Bad: Could delay us learning and using new features of the SF CLI. - -### Decision Outcome - -Here's how we plan to make this change: - -- **Maintain Backwards Compatibility:** Our priority is to ensure that all existing processes continue to function as expected. We will not modify the existing SFDX commands in our project until SF CLI announces the version in which these commands will be deprecated. - -- **Delegate maintaining backwards compatibility to the SF CLI:** We'll leave the existing commands, which invoke the `sfdx` alias from `@salesforce/cli` package, as is and rely on SF CLI to interpret these commands. We think this will make the change easier and less disruptive. - -- **Warn users that are on SFDX (v7) that they need to upgrade:** We'll check the installed version of the CLI and warn users that future versions of CumulusCI will drop support. - -- **Update our integration tests to include `stable-rc`:** We'll revisit PR #3558 to make sure all tasks that use the CLI are tested in our workflow, and that we're testing the weekly release candidate channel (`stable-rc`). - -- **Update the Falcon web applications to depend on SF as soon as practical:** We know we need to switch to SF CLI, and we want our Falcon web apps to benefit from its latest updates and features as soon as possible. We'll also install all necessary JIT plugins in the apps, so we don't have to install them over and over during builds. The timing of this switch will primarily depend on the team's bandwidth for testing the dependency switch and ensuring the `sf` CLI and JIT plugins are available. - -- **Update the SFDX Heroku buildpack to depend on SF as soon as practical:** Like the Falcon web applications, we want our [Heroku buildpack](https://github.com/SalesforceFoundation/simple-salesforce-dx-buildpack) to stay up-to-date with the latest SF CLI to get its performance and feature enhancements. Like the Falcon web applications, this includes installing all necessary JIT plugins for the buildpack. The timing of this update will also be dependent on the team's capacity to carry out the necessary updates and testing. - -## Consequences - -- Keeping things working as they are will cause the least disruption. -- By delegating backwards compatibility to the SF CLI, we can avoid making substantial changes to our command structure until it's necessary. -- Updating Falcon web apps and the SFDX Heroku buildpack to use the SF CLI will help us stay ahead of the change and avoid a scramble as the CLI removes deprecated commands. -- Installing JIT plugins in the apps and buildpack will make builds more efficient and avoid problems during runtime. -- However, this decision does mean that we will need to monitor Salesforce's communications closely for announcements about command deprecations, to ensure that our commands continue to function as expected. - -## References - -- [List of JIT plugins in SF CLI](https://github.com/salesforcecli/cli/blob/486a157c3d448d699c129f884bb3ab706523002a/package.json#L71-L81) -- [Salesforce CLI sf (v2) announcement blog post](https://developer.salesforce.com/blogs/2023/07/salesforce-cli-sf-v2-is-here) -- [CLI Deprecation Policy](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_dev_cli_deprecation.htm) -- [Issue #3621](https://github.com/SFDO-Tooling/CumulusCI/issues/3621) - - diff --git a/docs/adrs/0003-switch-to-sf-cli-in-cumulusci.md b/docs/adrs/0003-switch-to-sf-cli-in-cumulusci.md new file mode 100644 index 0000000000..06b309d7ed --- /dev/null +++ b/docs/adrs/0003-switch-to-sf-cli-in-cumulusci.md @@ -0,0 +1,67 @@ +--- +date: 2023-12-04 +status: Accepted +author: "@jstvz" +--- + +# ADR 3: Switching to SF CLI in CumulusCI + +## Context and Problem Statement + +Salesforce has deprecated SFDX (v7) in favor of the newer SF CLI (v2). Our web applications and other integrations currently depend on SFDX. To leverage new features and ensure support, we need to transition to SF CLI. + +## Decision + +### Considered Options + +1. **Support Both SFDX and SF CLI:** + + - Good: Provides flexibility for users still on SFDX. + - Good: Gives us time to fully understand the new SF CLI. + - Bad: Increases code complexity and could lead to inconsistent behavior. + +2. **Immediately Drop SFDX Support:** + + - Good: Lets us focus on the new SF CLI and stop worrying about old code. + - Good: Speeds up our switch to the new CLI and helps us find and fix problems sooner. + - Good: Gives us the opportunity to improve integration with the SF CLI. + - Bad: It could disrupt users' work if they're still using SFDX. + - Bad: There could be problems with the new SF CLI we don't know about yet. + +3. **Delegate SFDX Command Handling to SF CLI:** + - Good: Offers a smoother transition. + - Bad: Could delay adoption of new SF CLI features. + +### Decision Outcome + +We will make a decisive switch to the SF CLI: + +- **Discontinue SFDX Command Use:** We will replace all SFDX commands in CumulusCI with their SF CLI equivalents. This shift ensures that we are using supported and up-to-date tools. + +- **Update Integration Tests:** Our tests will be updated to reflect this change. We will ensure that all tasks are compatible with the SF CLI. + +- **Update Web Applications and Heroku Buildpack:** Our Falcon web applications and the Heroku buildpack will be updated to depend solely on the SF CLI. We will ensure that all necessary JIT plugins are pre-installed. + +- **Direct Warning to SFDX Users:** A warning will be issued to users who are still on SFDX, informing them of the need to upgrade to the SF CLI. + +## Consequences + +- This approach ensures that we are aligned with the latest Salesforce development tools and standards. +- Immediate transition may require rapid adaptation but ensures future-proofing and access to the latest features. +- Users of SFDX will need to upgrade, which may require some adjustment. +- Our codebase will be simplified by focusing on a single CLI tool. +- Installing JIT plugins in the apps and buildpack will make builds more efficient and avoid problems during runtime. + +## References + +- [List of JIT plugins in SF CLI](https://github.com/salesforcecli/cli/blob/486a157c3d448d699c129f884bb3ab706523002a/package.json#L71-L81) +- [Salesforce CLI sf (v2) announcement blog post](https://developer.salesforce.com/blogs/2023/07/salesforce-cli-sf-v2-is-here) +- [CLI Deprecation Policy](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_dev_cli_deprecation.htm) +- [Issue #3621](https://github.com/SFDO-Tooling/CumulusCI/issues/3621) + +