Menu

Topics

Best Practices for Maestro SCM Feature Branch Workflow

   Maestro This topic is related to Transact Maestro.  |   Form Builder Platform Developer |  v18.11 This feature was introduced in v18.11.

Introduction

Maestro Source Code Management (SCM) provides support for collaborative Transact form development using a flexible approach towards version control. This article provides an example of how to use Maestro SCM to implement a Git Feature Branch workflow.

The Feature Branch workflow scenario starts by creating an SCM project in Maestro and cloning it to your local computer. The Maestro SCM project source code is used to initialize a Git repository which becomes the source of truth for all subsequent development. While form development still occurs in Maestro, all version control activities, such as branching and merging, are performed in Git. In order to follow the Feature Branch workflow, Maestro projects are mapped to Git master and feature branches.

The following diagrams illustrate two perspectives on the relationship between Maestro SCM and Git in a Maestro SCM Feature Branch workflow. The first diagram shows how changes flow between Maestro projects and Git branches using Maestro SCM and Git commands. The second diagram shows how changes move between a project on a Maestro server and a remote Git repository on a Git server via the user's local Git repository using the SCM shell (also known as the SCM client) and a Git client.

These diagrams serve as a useful point of reference for the process described in this article. They are also used in this Maestro SCM v18.11 video to support an introductory explanation of how Maestro SCM is used in a feature branch workflow.

Prerequisites

This article assumes that:

  • The Maestro SCM shell is installed on your computer and you know how to start it.
  • You know how to create a Maestro form.
  • You have access to a Transact Maestro environment.
  • You Maestro user account has the SCM Project permission.
  • You have a working knowledge of Git.
  • You have a Git client installed on your computer.
  • You have a working knowledge of (and access to) a Git server, such as GitLab.
  • You are using a Windows computer. (The scm and git commands are operating system agnostic, but some Windows-specific commands and tools are used in this example.)

Maestro SCM Feature Branch Workflow

The Feature Branch workflow is implemented across three environments:

  • Maestro.
  • GitLab (or another Git server).
  • Your local computer.

The following diagram shows that the majority of commands are performed on your local computer using the SCM shell and your preferred Git client, while form development occurs in Maestro, and key Git actions happen on your Git server.

Follow these steps to implement a Maestro SCM Feature Branch workflow. The letter diamonds in the previous diagram are referenced throughout these steps using the format X. Sample scm and git commands are provided that you can adjust to follow along with the example.

Part 1: Getting Started

  1. Create a Maestro SCM project. A

    Login to Maestro and select your organization. Click Create Project to display the Create Project modal. Enter the required details and select SCM as the Project Type.

    Note

    SCM projects appear in the Navigator pane with a different icon than standard Maestro projects. This new icon shows at a glance that the project supports Maestro SCM.

  2. Create a form in your Maestro SCM project.

  3. Open a command prompt, start the Maestro SCM shell, and change to the directory that you want to clone your Maestro project into.

    scm.bat
    cd \c\projects\scm-example
  4. Clone your Maestro SCM project's source code. B

    The Maestro SCM command to clone your project's source code can be found on your Maestro project's Project Details page, in the SCM Clone field. The command is of the form scm project clone <org>/<proj> where <org> is your project's organization and <proj> is your project's name.

    Enter the SCM Clone command.

    scm project clone know/scm-example

    You can verify that your project's source code is on your computer and up-to-date using the dir and scm project status commands.

    dir
    scm project status
  5. Create a blank repository on your Git server. C

  6. In your Git client, execute the commands to clone the new repository and initialize it with the Maestro project files. These commands can be obtained from GitLab after creating the repository. Use the Existing folder commands. D E

    git init
    git remote add origin <path-to-remote-repo>
    git add .
    git commit -m "Initial commit"
    git push -u origin master

Part 2: Feature Branches

At this point, the Maestro master project and Git master branch have been created and initialized. We are now ready to create the feature branch and project.

  1. In your Git client, create a local feature branch. F

    git checkout -b "scm-feature"
  2. In your SCM shell, create a Maestro feature project using the scm project add command. G

    scm project add 'Add a new feature'
  3. Refresh Maestro to confirm that the feature project is now available. The Project Details page should show that it's of the type SCM Private. Only project owners and administrators have access to projects of this type.

    Note

    In the Navigator pane, feature projects are distinguished from the master SCM project by a differently colored icon.

Part 3: Feature Development

At this point, the Maestro feature project and Git feature branch have been created and are ready for development of the new feature. While the feature project is available in Maestro, the Git feature branch only exists on the local computer.

  1. In Maestro, open the form in the feature project, make necessary changes to implement the new feature, and save your form.

  2. Return to your SCM shell and check the feature project's status:

    scm project status

    You'll find differences between your local project and the remote project on your Maestro server.

    Update your local project with the changes from the Maestro server: H

    scm project pull

    When you pull the changes, you need to confirm which changed files to accept. You can type A to accept all file changes, N to reject all file changes, or Y to interactively accept or reject each file change.

  3. Return to your Git client and check the local repository's status. Git will report that there are modified files that need to be staged for commit. Stage and commit these files, except for scm.properties which we'll deal with later. I

    git status
    git add *.json
    git commit -m "Implemented the new feature"
    

Part 4: Merging Features

At this point, work on the new feature has been completed in Maestro, and the Maestro feature project and local Git feature branch have been updated. Next, we need to merge the feature branch into the master branch and update the master project from the master branch.

  1. In your Git client, push the local feature branch to the remote repository, thereby creating a remote feature branch. J

    git push origin scm-feature
  2. In GitLab, merge the feature branch into the master branch. K

    A good (and sometimes mandatory) practice is to merge the feature branch into the master branch via a merge request. When creating the merge request, you can choose to have GitLab remove the feature branch for you once it is merged. If you don't select this option, you can delete the feature branch manually after it has been merged.

  3. In your Git client, checkout the master branch and synchronize your local master branch with the remote master branch. L

    git checkout master
    git pull
  4. Checking the local Git repository's status reveals that the modified scm.properties file remains in the local working directory. As this file contains the project name, we want to restore the version of this file from the original SCM project created in Maestro before we update the master Maestro project. To do this, check the scm.properties file out of the master branch.

    git status
    git checkout scm.properties
  5. With the local working directory updated, we can now update the master Maestro project. M

    In your SCM shell, push the local master Maestro project up to your Maestro server:

    scm project push

    Then delete the feature project:

    scm project delete know/scm-example

Part 5: Project Cleanup

At this point, the master Maestro project has been updated with the work carried out in the feature project. You can confirm this in Maestro, then finish up by removing any left-over artifacts of the development process.

  1. Refresh Maestro to confirm that the feature project has been deleted.

  2. Open your master Maestro project and confirm that the changes made in the feature Maestro project are now applied to the master Maestro project.

  3. In your Git client, delete the local feature branch and the local tracking branch for the deleted remote feature branch.

    git branch -d scm-feature
    git fetch --prune
    

The Feature Branching workflow used in this article offers a simple approach to collaborative development, wrapping Maestro SCM commands and processes around a Git feature branching strategy. If, however, you prefer to use a different branching strategy, you can still use the Maestro SCM version control commands to manage version control of your Maestro project assets.