Development Workflow
Setting up a new Client with a development workflow
Overview
R3 recommends that development workflows are designed to control change management and allow clients a clean ongoing environment to undertake user acceptance testing (UAT).
The below diagram gives an overview of the structure, mapping git branches (white) with Salesforce orgs (red) and the transitions between them. It closely follows the Git-Flow methodology, but with some adjustments to deal with the uniqueness of developing against the Salesforce platform.
Branch Structure
Main
The main branch contains the current live version of the metadata
Develop
The develop branch contains the current iteration of code containing all features or work items that are complete
Release
The release branch (or branches) contain the latest iteration of completed features or work items that are available for client UAT. A consistent release branch can be used and update or a new release branch created for each release. If a new branch is to be created for every release, name it "release-x.x.x"
Feature Branches
Create a new feature branch for any piece of work. Use a naming convention to show what the branch represents; if it is for a single work item, name it after the work item, otherwise. name it for the feature being implemented.
Use sub-branches for work items and merge them into the feature branch if you want to keep track of work items separately.
Hotfix(es)
A hotfix branch should be created to make immediately available changes in a production org. Administrators should use hotfix branches and sandboxes to make their changes as this keeps all of the metadata consistent in the git repository.
Sandbox Structure
Ideally a Partial Copy sandbox should be used for "UAT" and a developer sandbox for "Dev" or "Develop". These sandboxes should only be deployed to via their corresponding git branches.
Continuous Integration
Ideally the following CI jobs should be set up to automate deployments from git to Salesforce orgs:
Git branch main -> Production (for releasing new code to production)
Git branch develop -> Develop Sandbox (for updating the developer sandbox to allow testing)
Git branch main -> Git branch develop (for hotfixes)
If a permanent release branch is being used, a CI job can be created to deploy it to UAT. Otherwise each branch will have to be manually deployed.
Initial Setup
Decide with the client who will have responsibility for hosting the source code during:
The initial development period
Permanently
If R3 or the client are to host the git repository, create a new Repository with the name "{Client Name}-sfdx".
Branch Structure
Once the metadata has been imported into GitHub into a "main" branch, immediately create a "develop" branch - this branch will be the source of truth for all new features created.
Sandbox Structure
Create a new sandbox (ideally a Partial Copy) called "UAT" from the client's org. Create a new sandbox called "Dev" from the client's org.
Continuous Integration
Ideally the following CI jobs should be set up:
Git branch main -> Production (for releasing new code to production)
Git branch develop -> UAT Sandbox (for updating the UAT sandbox
Git branch main -> Git branch develop (for hotfixes)
Salesforce Metadata
In an ideal world, all the metadata from Salesforce should be stored in a git repository enabling anyone to re-create the production org at any time. In reality there are some challenges with this. There are some metadata types that it is wise to exclude and some which need an eye kept on them during the development process.
Excluded Metadata
This list of metadata to exclude includes items that either should be different between sandboxes and production orgs or is easily changeable by standard users. We do not want to override user-created metadata from source control.
List Views
Reports
Dashboards
Site.Com
Flow Definitions
Named Credentials
Auth Providers
Connected App
Keyword List
Metadata to be aware of
Some of the metadata within Salesforce is affected by the type of org being used - there are production specific values that do not get transferred into sandboxes and therefore these changes should not be checked in to git. This list is not exhaustive, so watch out for anything that's altered but not specifically related to the feature changes whenever making a commit.
Some of the metadata in XML format is simply re-arranged, it is advisable to ignore these changes too.
Custom Applications (Environment Hub settings removed on sandbox)
Lightning Page (Environment Hub)
Layouts
Moderation Rule
Network Branding (Community Branding)
Profiles
Settings (EAC settings removed on sandbox)
Custom Object Translations
Last updated
