Version Control with Git

info

This feature is only available on Holistics 4.0 (Analytics As-Code)

Introduction

With all of analytics logic being described as code using AML, it is natural to be able to check them into a revision control system such as Git.

With Holistics's Git Integration, your Holistics codebase is now powered by Git. You can track every change, perform code branching, change reviews for a better analytics development workflow.

Benefits:

• Version Control: Track and manage every change in your analytics logic.
• Isolated Environment: Develop your work in a branch to avoid affecting other people. Deploy only when you are confident with your changes.
• Code Review (Merge Request): Have someone else double check your code before deploying to production.
• Code Backup: Back up your analytics logic into a separate repository for backup purposes.

High-level Mechanism

Behind the scenes, Holistics maintains Git repositories to host the code changes. Holistics also exposes a Git-friendly UI interface for users to commit changes and deploy to production.

There are three different Git repository concepts with Git Integration:

• System Repository: Git repository that Holistics maintains internally on the server for the analytics code.
• User Repository: Holistics-managed repository for each user.
• External Repository: Repository that sits on customers’ servers or Git providers (like Github or Gitlab)

You have the option to either use Holistics' default repository, or connect to your own external Git repository:

Without External Git repository

With External Git repository - Holistics Cloud Editor

How it works

From the user's perspective, the workflow follows a simple three-step process:

• Create branch: User creates a new branch (in their User Repository) to start their development.
• Make changes & commit: User makes their code changes and commit (to User Repository). It is then pushed automatically to System Repository.
• Deploy: Once happy with the changes, user presses deploy to production. Their code will then pushed to System Repository's master branch (production branch). Live reports and dashboards are updated with the new code logic.

Development Mode vs Production Mode

Please refer to this document to learn more about the difference between the two modes.

Managing branches for Development Mode

Create branch

To start making changes, you need to create a new branch (in Development mode). You are not allowed to make changes directly to Production environment.

When creating a new branch, you're asked to choose a base branch (aka branch to fork from). If your change is new, you should fork from master (production) branch.

Notes before creating a new branch:

• If you have a merge conflict on your current branch, you must resolve the conflict before you can create a new branch.
• If you have any uncommitted changes on the current branch, you must commit the changes on your current branch before creating a new branch.

Once you're in a new branch, go about making your changes using Holistics's Cloud IDE. Once you're happy with it, commit your changes.

You can make as many commits as you want. Similar to software development, it's recommended that you break your changes into multiple small, meaningful commits rather than a single large one.

Delete branch

If there are branches that are no longer useful for development and you want to clean up them, you can delete them in branch management

However, do note that even if you delete a branch, if that branch still exists in another repository of another user and he (or she) pushes it back to System repository, it will be once again presented to your branch list.

The reason for this is that you can only delete branches in your user repository and system repository, you will be unable to touch other people's repository.

Deploying to Production (Go Live)

When you are happy with your changes in your development branch, you can deploy them to production. Click on "Deploy to production" on top top right corner of the page.

Changes pushed to Production (master branch) are automatically applied to the Reports, Dashboards (Reporting tab).

In order to deploy to production, your current branch needs to be ahead of the Production branch. If not, you will be asked to Pull changes from Production before proceeding with the deployment.

Resolving Merge Conflicts

You should know

A merge conflict arises when two Analysts make changes in the same line in a file, or one Analyst deletes a file but other Analyst makes edits in the same file.

There are bound to be merge conflicts when you pull changes from other branches. Should this happen, Holistics will use the standard Git syntax conflict markers (Learn more) to display conflicts during merging.

The merge cannot be executed automatically because Git cannot determine which changes to keep, so you will need to resolve the conflicts manually.

To resolve a merge conflict, follow these steps:

1. Select which changes you want to keep: their branches, your branches or both. If you want to discard a change, simply delete the corresponding code section.
2. Then, Delete the conflict markers.
3. Commit your changes.

Syncing with External Repository

info

💡 This feature is not supported yet in the Beta version of Holistics. It should be supported eventually when Git Integration comes out of Beta.

Holistics supports syncing from System repository into your own external Git repository stored in Github or Gitlab. The syncing will be two ways:

• You can push from System Repository to External Repository for backup and external viewing purposes.
• You can make your own commits to External Repository, and push to System Repository to "deploy production"

Using your own IDE editor: Once support for syncing with External Repository is released, you can use your own code editors (e.g., VS Code) to do analytics development on your local environment, and deploy by simply pushing to System Repository.