How do you setup version control of Procedures?

A quick overview of best practices when setting up Git as version control of Procedures.

Intro

In order to ease collaboration and keep track of changes and versions we recommend using a version control system like Git when working on procedures in SynergyXR. Incorporating a good routine with using version control has several benefits:

• It makes collaboration in teams easier: Get newest updates to procedures from colleagues easily, branch off to make experiments, and view history to assess changes.
• It makes it easy to restore earlier versions of procedures: Recover from accidental file deletion or corruptions.

This article is not meant to be a comprehensive guide to version control of software in general nor Git specifically. We merely aim at providing an overview of best practices to set you on the right path.

Software recommendations

We recommend using the following software:

• Use Git as version control system since this is widely adopted and well supported.
• Use Git LFS for large files like models, images, etc.
• Use a UI-based version control app like Atlassian Sourcetree.

Workflow recommendations

When collaborating on procedures using Git:

• Clone repositories: When working on a procedure on a new computer, clone the procedure repository from Git and then open the procedure in the Procedure Builder. This ensures that you have the latest version of the procedure and that you are able to push your changes to the repository.
• Pull changes: Before opening a procedure in the Procedure Builder, pull latest changes from the repository to make sure you have the most up-to-date version of the procedure. This ensures that you don’t work on an older version of the procedure and is unable to push your changes without merging.
• Commit and push changes: Whenever you are finished working on a procedure - or when you have made significant changes - remember to commit the changes and push them to the repository. That way you are sure that others will pick up from that version and that you can always restore the procedure to this point of time.
• Coordinate with colleagues: Give your colleagues a heads-up that you are working on a specific procedure if there is a chance that others will be working on the same procedure. That way you minimize risk of doing conflicting work and having to merge Git changes. Merging is troublesome!
• A Git repository for each procedure: Each procedure should have its own repository. This will keep Git history clean and make sure that you at any point of time can checkout individual procedures in the version you want to work with.

File structure recommendations

When using Git for version control of Procedures, we recommend you do all synchronization of work through pull/commit/push Git operations as described above and avoid using the “Override local copy with online version” offered inside SynergyXR. 

We recommend the following directory structure if you expect to pull latest changes to procedures using Git:

This is the recommended directory structure when working with Git; that is, a Git repository for each procedure.

If you plan to use the “Overwrite local copy with online version” functionality often, then you should create a procedure directory inside the Git repository to hold all procedure files for one procedure in order to avoid deleting the Git repository. This will result in a structure like this:

Git LFS

We recommend that the following files are added to LFS (.gitattributes content):

# Images
.jpg
.png

# Models
.glb

# Sounds
.ogg

# Videos
.mp4
.thumbnail

Git ignore

Per default all files should be added to the repository, unless you have specific files you want to be ignored. On Mac you can add this to .gitignore:

# Mac
.DS_Store

Setting up a new repository from command line

In project root:

$ git init
$ git remote add origin git@server.com:user/repo.git  # Replace with appropriate values
$ git lfs track "*.jpg" "*.png" "*.glb" "*.ogg" "*.mp4" "*.thumbnail"
$ echo ".DS_Store" > .gitignore
$ git add *
$ git add .*
$ git commit -m "Initial commit"
$ git push -u origin main