Open Sourcing Salesforce CLI Update Feb. 2021
This is the second blog post that details the Salesforce CLI team’s progress towards 100% open-sourcing of the CLI code. If you haven’t read the first post, or need a refresher, check it out here.
Now that you’re all caught up and refreshed, you probably have two questions: “It’s been eight months, what happened?” and “What progress has been made in that time?” We’re excited to share that a lot has happened. We wrote the first blog post to explain where we were and where we wanted to go. Since then, the CLI team has created an easily extensible framework for other engineering teams to use in following our lead and open-sourcing their commands. Developing the framework involved creating plug-in templates and CircleCI orbs to allow other dev teams to skip over the setup and integration steps and start coding their plug-ins right away. These frameworks were the basis for moving everything into plugins – I’ll get into more detail about how they helped later.
Before diving into our current status, let’s go over some of the promises and goals of the first blog post and check our progress towards completion.
In the first blog post, we teased that we’d create “A GitHub organization for Salesforce CLI”. Good news, we’ve accomplished that goal! You can browse the GitHub organization here: https://github.com/salesforcecli. This is where we put all of our new plug-ins, orbs, templates, aggregators, and monitoring repositories. When we create anything new, we’ll put it in that organization for you to keep an eye on and see how we build things in the open.
We’ve kept our current issues repository (https://github.com/forcedotcom/cli/issues) and moved the release notes to the same repository (https://github.com/forcedotcom/cli/tree/main/releasenotes.)
We’re deep in the trenches of breaking up the
salesforce-alm plug-in. At the time of this writing, there are at least 40 open-sourced commands in the organization’s repository spread across 11 different plug-ins, and we don’t plan on slowing down anytime soon. I’ll go into more detail about this process later in this blog post.
We’ve also created a status repository (https://github.com/salesforcecli/status) that monitors the other repositories in the GitHub organization. Here you can check the version of a specific plugin, when it was last published, its current build status, and the overall health of the CLI and its components.
Any new code or repositories the team creates will be made in the open. Our team has fully committed to 100% open source work from now on.
Breaking up salesforce-alm plugin
Just take a peek at https://github.com/salesforcecli to see all that we’ve been working on over the past eight months. Once we settled into a rhythm, the team started migrating into new plugins very quickly. Each repository corresponds to a plug-in. Here’s the current status of the plug-ins we’ve open-sourced:
||Currently In Progress
||org (part 2)
||org (part 1)
Some plug-ins have been brought to the top level, which means, for example, that you now run
sfdx config:set instead of the old
sfdx force:config:set. We’ve completed this work for the
config topics. But don’t worry, we’ve aliased them so they also work under the
force namespace, which means your current scripts won’t break. However, we highly recommend that you start using the new command names as soon as possible.
From the table above, you can see that we’ve made great progress towards open-sourcing everything! Unfortunately, some of the remaining topics to be broken out, specifically
source, are the most complex and will take the longest to open source. We are prioritizing them over the next year.
Back in the first blog post, we said that more and more plug-ins would be under
salesforcedx and even outside of it too. Run
sfdx plugins --core to see our progress and how we’ve accomplished what we said we would.
Now releasing: plug-ins and the CLI
When we began open-sourcing the CLI code, we knew that we would also have to change how we released the CLI. Instead of releasing a mono-repo structure, we now release new versions of multiple plug-ins. These are then consumed by one or more aggregators and we ship that end result. In theory, this process isn’t too difficult to implement, but in practice it took a lot of work to create a reliable and reusable CircleCI orb. Now, a PR merge from a develop branch into the main branch of any plug-in’s repository automatically kicks off a release of that plug-in. It’s then automatically published and promoted to a new version on npm, and then listed as a dependency of one of the aggregators. Here you can see the
plugin-user plugin listed as a dependency for the
We place all commands that are under the
force namespace (such as
force:schema:*) in the salesforcedx aggregator. Plug-ins for commands outside of the
force namespace (such as
plugin-auth) are included directly from the
cli repository, and thus you run these commands using
latest-rc version is only available via npm. To test it out you would run
npm install sfdx-cli@latest-rc. It’s not quite available yet for the standard installed version of the cli, but it’s coming soon. In the future you could run
sfdx update stable-rc . Although
latest-rc will point to the same version, the names are different because using
latest-rc is an npm convention, so we’re using it for npm-based installations. The
stable-rc are an OCLIF convention. So you have a one week window to test it out, and, if you find any bugs, make sure to post them in the CLI issues repository with
latest-rc tag and the version number. Below you can see that the
latest-rc tag is pointing to version 7.87.0 and the
latest tag is pointing at 7.86.3.
We provide the
latest-rc tag for people to preview what’s coming, test new features, and ensure that it’s ready for its promotion to
latest. Once promoted to
latest it is “live” and the current version. The CLI team highly encourages everyone to use the
latest-rc tag as much as possible. To ensure compatibility, we suggest you update your release processes or scripts to use both tags. Check out https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_ci_org_dev_repos.htm for a variety of CI/CD platforms and their respective configuration files.
Let’s close our eyes and imagine this scenario: you think of a feature that will benefit other users, or you come up with a bug fix, or you dream up a quality of life improvement that everyone would love. Instead of opening an issue and marking it as a ‘feature request’, we encourage you to dig into the source code and work on it yourself! You’ll get great experience understanding how a specific command works behind the scenes, which in turn can help you optimize your own workflow. We accept pull requests to all of our open-source repositories. If you create a PR, you’ll work closely with the CLI team as we go through iterations and reviews. If your PR is merged and released, I’m sure you’ll be happy using your new feature. And the CLI team will be over the moon seeing an outside collaborator successfully closing a pull request!
What if you have some very complex conditionals and custom interactions that you’re executing in a script? Or you’re doing some API wizardry that could benefit from being placed within a command? It’s not logic everyone needs, but for some it would be a game changer. How do you easily distribute this to other members on your team or the community to use? An sfdx plug-in! Luckily, we have the plugin-template repository, which contains everything you’ll need to get started on coding your very own plugin. This includes CircleCI orbs to use, eslinting rules, commit validation, backwards compatibility checking, and OCLIF support right out of the box. The template is set up to use the latest TypeScript and eslint targets. The
plugin-template repository was created using the
sfdx plugins:generate command. It was then added to create a standardized repository for the rest of the plugins. If you want to see the power of plugins yourself, take a look at what one of our engineers, Shane, has created with his shane-sfdx-plugins plugin.
We’ve made great strides towards achieving a 100% open-sourced CLI from Salesforce. There are a few hurdles left, but at this point we’ve done most of the hard work and the runway is clear for us to continue. We won’t stop until we’ve open-sourced as many commands as possible!
Hopefully now, as a reader, you’ll feel more comfortable creating a pull request for fixing a bug or adding a new feature, and then understanding how it will be released and when you can expect to see your change live. We’re all incredibly excited about our progress and where we’re going. We can’t wait for you to see what we’ve been working on!
Remember to check the release notes every week to stay up to date with new features, fixes, and requests for comments (RFCs) – where you can influence our design process.
About the author
Willie Ruemmele is an engineer on the Salesforce CLI team. This is his first job after graduating from the Colorado School of Mines in 2019. He started working at Salesforce as an intern, and now has been working full time for almost one and a half years. When he’s not working he enjoys mountain biking, rock climbing, surfing, and snowboarding.