Our branch management system is inspired from distributed revision control systems. Here are the principles:
Every Studio project is initialized with a
master branch which is the main branch of your project. It should be used to perform the main release. The
master branch cannot be removed. You can create as many branches as you need. Typically if you want to start working on a new feature that will take some time and don't want that work to be displayed with the rest of your customization in Studio (and the Platfform) until it is finished, you should create a branch for it. You can also create a maintenance branch to separate maintenance developments from evolution development. A new branch is always based on existing one, so a new branch is not an empty one.
Users can merge and delete branches.
Common Branch and User's Workspace
On a project, branches are shared by all the developers. They are named common branches. To work on a given branch, user needs to "check out" that branch. Behind the scene, it creates an other branch from the checked out branch and all edits of the user will happen on that branch. The user's workspace is the list of all the branches that have been checked out. This workspace is strictly personal and those checked out branches are never display anywhere else, neither shared to anybody. The user needs to push the changes to the common branch to make them available for others. Depending on the save mode, this can be automatic when the user saves (Simple save mode) or manual (Intermediate and Advanced save modes).
If other users have modified the common branch before the changes were pushed, a pull icon is displayed. The user can then pull these changes to their local branch so it now holds the latest state of the common branch and their own modifications. Sometimes a conflict can happen, see the "Handling Conflict" section later in this page.
Commit, Pull, Push
Commit: A set of changes performed on one or multiple files. It's an evolution of your project between the state after the previous commit and the new state. A version of the project is the result of a sequence of commits from the moment you created the project.
In simple mode, you have one commit per change: One change on a single feature, a resource added, the application changed, etc.
In advanced mode, the changes are stacked until the user decides to commit them by clicking on the icon. The user will then add a commit message to describe the set of changes and will commit the changes on their workspace.
Pull: Refers to when the user wants to update their workspace with the changes performed by other users in the common branch. For instance, if someone has also modified a part you are working on, you'll want to pull those changes to your workspace so that it's up-to-date.
By clicking the icon the user will update their workspace with changes from the common branch.
In simple mode, a pull is performed each time the user refreshes the project. The user is notified by the icon when another user commits some changes on the branch they are working on.
Push: Happens when the user wants to share local commits with others.
By clicking on the icon the user will push the changes committed in the local branch to the common branch.
In simple mode, the push is performed automatically for each save.
A conflict happens when two users work in the same version and made different changes on the same data (feature, file, application dependencies, ...).
The conflict can happen:
- When the user shares some changes: Push (or a "Save" in simple mode)
- When the user gets some changes: Pull
When a conflict is detected, a dialog window is displayed. It contains, for each file in conflict, the sections affected. User selects the file to keep (the local one, or the version coming from the common branch).
The conflict management is currently a binary choice per file. The user cannot decide to keep a part of a given feature and get another part of the same feature from the common branch.
After resolving all the conflicts, a push on the common branch might be necessary (depending on when the conflict occurred).