Flowing changes

As the name implies, OrgFlow is fundamentally about flowing metadata changes between Salesforce orgs.

Flow operations

There are three flow operations in OrgFlow, each documented in its own topic:

Operation	Figure	Description
Flow in		Detect and retrieve new metadata changes from an environment's Salesforce org and commit them to its backing Git branch
Flow in		Determine undeployed metadata changes in an environment's Git branch and deploy them to its Salesforce org
Flow merge		Merge metadata changes from a source environment into a target environment, while optionally retrieving from the environments' Salesforce orgs, and deploy the merged changes to the target environment's Salesforce org

Depending on context, we also sometimes refer to these as inbound flow, outbound flow and merge flow, respectively.

Why "flow"?

You might be wondering why we call it "flowing" as opposed to just "retrieving and deploying", "copying", "moving" or "syncing". We use the word "flow" to mean an intelligent end-to-end change migration process that involves more than those things.

OrgFlow's magic lies in what these flow operations have in common:

• Flow migrates changes - unchanged metadata is ignored (unless forced)
• Flow automatically determines new changes
• Flow migrates changes via a Git repository — not directly from org to org
• Flow migrates changes via merge — not copy/paste
• Flow persists changes only no unexpected errors occur during the process
• Flow enables partial success and eventual consistency allowing changes to converge over time despite temporary discrepancies
• Flow involves environments in a stack — not arbitrary Salesforce orgs
• Flow is driven by environment state such as unmerged commits or undeployed changes

As you will see, things like retrieving, committing, merging and deploying are only parts of the larger overall change flow processes. Throughout this documentation, you will notice we use those words to refer to those smaller operations specifically, while using the term "flow" and "flowing" to refer to the larger overall change migration processes.

Making changes in production

Many teams using Salesforce are used to — and greatly appreciate — being able to customize it directly in production. This is one of the long-time strengths of Salesforce, because it makes the system so easy to tailor, with minimum ceremony. Even as teams start using sandboxes for more complex customization efforts, many still find it sensible to allow some smaller, simpler and more atomic metadata changes directly in production, without the added hassle of deploying them from a sandbox.

Are changes in production inherently bad practice and incompatible with DevOps? Absolutely not, as long as there is adequate tooling in place to efficiently and safely handle it. OrgFlow fully supports changes made directly in production, through its ability to flow changes between environments bidirectionally, using the inherent merging and conflict resolution mechanisms in Git to safely reconcile the differences.

Upstream/downstream

While the environments in a stack are all related, they do not form an inherent structure within the stack. All environments in a stack are equivalent from a change flow perspective, and you can flow changes between any two environments as you see fit. There is technically no concept of downstream or upstream relationships between any two environments, nor are there any constraints forcing users to propagate or promote changes in any particular stages.

However, in practice your Salesforce DevOps process will usually form an implicit directional stream of changes, where changes originate in development/feature sandboxes, flow via testing/staging sandboxes, and ultimately end up in your production environment.

It is therefore very common in Salesforce DevOps contexts to reason about metadata change flow in terms of downstream and upstream. Flowing changes downstream means to flow them closer to their ultimate destination (typically your production environment), while flowing changes upstream means to flow changes in the other direction (sometimes called back-promotion or back-propagation).

Similarly, if changes typically flow from environment A to environment B on their way to their ultimate destination, then B is said to be downstream of A and A is said to be upstream of B.

For admins and developers with a Salesforce background, who may not be accustomed to reasoning about change flow in these terms, the following illustration might be useful to help remember what downstream and upstream mean in a Salesforce DevOps context:

Back-promotion of changes

When a sandbox environment is created, its metadata starts out more or less identical to that in your production org. As time passes, the metadata in your production org changes. Metadata changes typically happen in your production environment for a variety of reasons:

• Changes are merged from other environments in your stack
• Admins make changes directly in production
• Changes are deployed to production using change sets or some other third-party Salesforce deployment tool

This means that, even if you make no changes to the sandbox, it starts to diverge or drift from your production org. The longer the sandbox exists, the more changes end up in production from elsewhere, and the farther the sandbox drifts.

Left unchecked, this drift can present challenges:

• Development in the sandbox is not based on the latest most relevant code
• Hard or impossible merge conflicts when the sandbox changes are merged downstream
• More failing components when the sandbox changes are deployed to downstream Salesforce orgs

You can mitigate these challenges by ensuring that you continuously back-promote changes from production to upstream environments. This helps keep metadata changes aligned across all the environments in your stack, encourages more frequent releases, and reduces the likelihood of experiencing environment drift and deployment challenges.

OrgFlow makes it easy to set up continuous back-promotion of changes by configuring nightly upstream merge to run on a schedule.