This how-to guide for ISVs is contributed by the awesome Eric Kintzer, Salesforce Architect at Helix, and Gearset Community Advisor.
If you’re an ISV with a first-generation managed package, you can use Gearset to improve your DevOps flow. This is true whether or not you use version control. In this post, I’ll describe what the developer workflow usually looks like without Gearset, and then explain how to set up a better workflow with Gearset.
A typical ISV org landscape
First, let’s consider what kinds of org ISVs normally use to develop and maintain a first-generation managed package.
- Packaging org. The org that contains your namespaced metadata such as custom objects, process automation, Apex, layouts, Lightning pages, and more. This metadata is added to your managed package, either as a beta or release package.
- One or more (partner) developer edition orgs. The orgs where new features are built by your engineers. These orgs can be created from the Environment Hub, or directly, and contain metadata that isn’t namespaced. You might be using scratch orgs in lieu of developer edition orgs.
- Production/CRM org. A Salesforce org to help you manage leads, cases, opportunities and more. If using scratch orgs, the production/CRM org is designated as the DevHub.
- AppExchange publishing org. The org used to manage your use of AppExchange. Frequently, this function is subsumed inside the production/CRM org.
- License management org. This org keeps track of licensed uses of the ISV application. Again, this function is often subsumed inside the Production/CRM org.
- One or more testing orgs. The orgs used to install your package and test upgrades.
Developer workflow without Gearset
Metadata needs to be moved between the orgs listed above as part of the developer workflow. Your packaging org should be used for packaging releasable components - and nothing else. Developing new features should happen in your developer org.
Without version control
For each new feature, you first need to get the metadata from the packaging org into your developer org. Typically, this is done using the Ant migration tool and Apache Ant scripts, but you could also use Workbench for the deployment. The Ant migration tool is run from the command line, or terminal within an IDE. You need to maintain a package.xml file that enumerates the metadata to be retrieved from the packaging org so it can be deployed into the developer org.
Once you’ve finished development, you use the Ant migration tool again to deploy changes to QA orgs and then directly back to the packaging org.
With Version Control
If you’re using version control the process is similar, but you’ll be using your main branch as your source of truth rather than a packaging org. So when you’re going to build a new feature, you’ll need to get the latest metadata from the main branch and deploy it to your developer org. Your package.xml file will be kept in version control.
Once you’ve finished developing the feature, you deploy the changes back to version control. If you’ve invested in a continuous integration platform like Jenkins or TravisCI, you can then automate the deployment from version control into a continuous integration org or staging/QA org. An excellent description of this developer workflow can be found in Chapter 13, ‘Source Control and Continuous Integration’, of Andrew Fawcett’s Force.com Enterprise Architecture.
Problems with the workflow
This workflow is far from ideal. Whether you have version control or not, you end up with running scripts, and, when errors ensue, analyzing terminal output. Being in the right local directory matters a lot. Often, it’s a wing-and-a-prayer that you remember all the metadata that needs to be deployed. And, without more sophisticated scripts, rollback is complicated. While this might be second nature to full stack developers on your team, none of this is friendly to point-and-click developers.
Developer workflow with Gearset
Your workflow for developing and maintaining first-generation packages can be improved with Gearset. Here’s how to create a better process using Gearset and its integration with version control. Once set up, the workflow will work like this:
1. Make version control the source of truth
First, define a repo in your chosen version control system (VCS), such as GitHub. Then populate the main branch with the metadata from your packaging org’s managed package, using Gearset in the following way.
Pro tip: As a prerequisite, none of your Apex classes or Visualforce pages should reference any custom object by their namespaced name. For example, if your package’s namespace is foo and you have a custom object called Driver__c, be sure your Apex classes or Visualforce pages reference Driver__c, not foo__Driver__c.
In Gearset, choose or construct a metadata filter that contains all the metadata types used by your managed package. And, most importantly, explicitly identify the package’s namespace in the managed package section of the filter. In the example below, the package’s namespace is fforceek.
Don’t include:
- Standard objects (but do include your managed package’s custom fields on standard objects)
- Standard applications
- Layouts on standard objects
Once you’ve deployed the metadata from your packaging org’s managed package to your version control system, the repo’s main branch will be populated using Salesforce’s source-format directory structure. It will look like this:
2. Populate your developer or scratch org with the latest metadata
Since you may have multiple developers working against your version control main branch, you’ll want to spin up a new developer org or scratch org to work on a new story or functional requirement. This org then needs to be populated with the latest metadata.
Use Gearset again to compare and deploy the metadata between environments. The source should be your main branch; the target will be your new developer org or scratch org. Choose a metadata filter that includes all the metadata you plan on working with. For this deployment, you don’t need to include the namespace in the filter - although leaving it in place does no harm. Both version control and your developer orgs are not namespaced. Namespaces are added once you deploy back to the packaging org.
3. Develop your feature
Do whatever you need to do! Add/change Apex, Lightning pages, Aura components, Lightning Web Components, flows, permission sets - you name it.
4. Commit back to version control
Use Gearset again and deploy your changed/new/deleted metadata back to a feature branch. Your Gearset metadata filter should include everything that you worked on and shouldn’t include the namespace. These deployments double as commits to the branch.
Once you’ve committed those changes, do a pull request, get your changes reviewed and then merge to the main branch. If you’ve set up continuous integration, changes to the main branch get built and deployed against a CI org and/or a QA org. Once again, these are non-namespaced orgs.
5. Deploy to packaging org
Once you know your CI jobs have run and any QA tests have passed, use Gearset one final time to deploy your story (or stories) from version control to the packaging org. Your metadata filter needs to include the namespace this time, otherwise your metadata will look like it’s new, when in fact it’s just been changed.
Try it for yourself!
The best way to find out how Gearset’s Salesforce CI/CD solution can help you is to try it out for yourself! Sign up for a free trial, and should you need any help, Gearset’s support team will be on hand to solve your problems. From within the app, or here on the website, just open the live chat and get the answers to your questions!
You can also learn more about version control best practices and get practical advice for implementing version control in your business by downloading our free whitepaper.
