Version Control Reliability & UX

Hi everyone,

We recently received a question asking if we had any recommendations about how to use the version control feature as it currently is. We thought it might be helpful to share these responses with everyone and this thread is a great place to do so!

We first wanted to address some information about what actually happens when you add changes from one version to another. When adding changes from one version (say Version 1) into another (say Version 2), here is how we determine what updates will be made and what conflicts will be generated:

  • If something (whether it be an element, an action, a property…) has been updated (or added/deleted) in Version 2 but has not changed (or never existed) in Version 1 then that thing should not change in Version 2 after you add changes from Version 1 into Version 2.
  • If something (whether it be an element, an action, a property…) has been updated (or added/deleted) in Version 1 but has not changed (or never existed) in Version 2 then that thing should be changed in Version 2 to match the updates that were made to this thing in Version 1 after you add changes from Version 1 into Version 2.
  • If something (whether it be an element, an action, a property…) has been updated in both Version 1 and Version 2 and the updates in each version are different from one another, then when you add changes from Version 1 into Version 2, there will be a conflict raised in Version 2 for the particular thing that has been updated.

When adding changes from one version into another, there may be many changes that have been made to one or both versions since the last time these two were synced up. In that case, for every change detected, the above comparison will be made to determine what the outcome of adding changes from Version 1 into Version 2 should be.

When comparing the two versions to see what has been updated, we do not simply consider all the differences between the two versions. Instead, we actually use a snapshot of what the version that you are adding changes from was the last time these two versions were synced. The time when these two versions were last synced gets updated each time you add changes from one version into another. As a result, the next time you add changes from Version 1 into Version 2, we will not be applying again the changes that had already been considered the previous time you synced the versions. Hence, if you try to add changes from a version into another version without having made any updates to either version since they were last synced then nothing will happen.

We also wanted to share some recommendations about how to use this version control feature.

  • In general, we recommend keeping your Development version as a “main” version that you will add changes from other versions into, create other versions from, and deploy to Live.
  • If you want to create a new feature or a quick fix, our recommended approach would be:
    • Create a new version named after the feature you are working on from Development
    • Work on that new version and, when ready, add the changes from that version into Development
    • Check in Development that your changes were successfully added and that everything works as expected
      • Please visit all of the pages that could have changed after the sync in your editor to make sure the updates have been made (some elements or issues might take a little bit of time to appear for large apps).
      • If you notice that anything was not added then please reach out to our team so we can investigate this situation as part of our ongoing work to improve the reliability of this feature
    • Deploy your Development version to Live
    • Delete the feature version you used and for the next features/fixes, create versions off of the updated Development version
  • We recommend using this approach of a version per feature rather than a version per developer because, in general, things get more complicated the longer different versions exist in parallel, differ from one another, and get changes added from multiple other versions.
  • Following a similar reasoning, we recommend that the lifetime of versions (other than Development and Live) be kept as short as possible.
  • We also recommend that if you are working on a fix or feature in one version, that you do not edit the relevant items (elements, workflows, page…) in another version. This will help to limit the number of conflicts that are raised when syncing the two versions.

We recognize that this approach might not work in every case but these are some general recommendations that we would make.

I hope this was helpful. We’ll continue to keep this thread active as we improve this feature!

13 Likes