|Table of Contents|
LieberLieber recommends GitFlow when working collaboratively with models under SourceControl.
This workflow is established in Software Development and also very useful when working with Enterprise Architect models (.eap(x)) and Git.
This content is also available as a presentation in German: GitFlow mit EA Modelle.pdf
Note: The following description is based on using the UI TortoiseGit with LemonTree integration to interact with git:
|Example Tool Chain|
|Version Control System:|
|Diff & Merge Tool|
LemonTree (c) Desktop
Why should I use GitFlow?
Working with GitFlow brings multiple advantages to your modelling approach:
- Multiple different Change Requests/Features can be modelled at once without interfering with each other
- Reviews can/must be made at a clearly established step in the workflow
GitFlow: Feature-based Development
- You do not work directly in "develop”.
- Each change (CR/Feature) is incorporated via a "Feature Branch".
- After the work is done by the modeler, the branch is reviewed and brought to "develop".
The following is a description of the process using the GIT client TortoiseGIT (https://tortoisegit.org/) .
The general information is applicable for any git toolchain you may be using in your company, or even when using direct git commands as well.
1. Create a new "Feature" Branch
To create a new feature branch directly from "Develop", check the "new branch" box in the commit dialog and enter the new branch under "Commit to" according to the naming convention.
Tortoise-GIT then automatically switches to this branch and you can continue working and add new commits.
- With the "commit", the branch exists locally in the clone of the repository.
- With the first "push" it also reaches the "remote" repository.
2. Update my Feature Branch from „Develop“ via Rebase
To keep the feature branch up to date, rebase it to “develop". This puts the “develop's” new commits into the feature branch before its own commits.
What's happening here?
3. Move feature branch to "develop"
3.a Prepare Feature Branch for Reintegration
Before merging back the branch we want to compress it to have a clean history. The goal is to have only ONE commit per feature/task.
This requires 2 steps:
- Step 1: Combine Commits
- Step 2: Push the new, combined commit to remote
Step 1: Combine Commits
1. In the "log" of the Feature Branch several subsequent Commits are selected
2. These are combined using "Combine to one commit".
3. A new, final commit comment is assigned. System default should not be used, since all commit comments are simply appended to one another. Instead, a meaningful description of the overall change or the task should be considered.
Step 2: New, combined commit, push to remote
After combining, the change is pushed to the feature branch. With this we rewrite the history of the feature branch and
Force: May discard "known changes"
has to be checked. So GIT knows that's our intention. Otherwise the push will be rejected.
3.b Perform Review
1. The finished feature branch is checked by colleagues/reviewers before being returned to "Develop".
Perform the review via LemonTree. To compare 2 revisions,
a) select them in the "Show Log" menu of TortoiseGIT.
b) Click "Compare revisions"
c) Double-Click on the .eap file you want to review.
Since LemonTree is integrated in TortoiseGIT it will be automatically started when a workflow is used for performing a diff on eap(x) files. For example comparing branches via Revision Graph.
=> LemonTree provides the possibility to flag elements as "Reviewed" and filter for "Reviewed" elements. Details: Impacted Elements / Impacted Diagrams List
=> LemonTree provides the possibility to save sessions. This enables the user to save the current state of review and transfer sessions. Details: LemonTree Session Handling
2. If Review OK --> Continue with step 3.c --> integration back to "develop".
3. If Review Remarks --> Back to the modeler and after incorporating the changes start again with step 3.
3.c Merge back feature branch
1: Select the merge command (from "develop")
2. Select feature branch
If you check "Fast Forward Only", Git does not create a merge commit.
3. Push the merge
The merge is only in your local clone of the repository. Perform a "Push" to the remote.
4. Delete Feature branch locally and remotely
- The working steps were demonstrated with the Git client "TortoiseGit". Other clients can also be used, also in combination (SmartGIT, GitLab, SourceTree, ...).
- When using the workflow "GitFlow", the "Develop" branch is always "stable". Only fully modeled features/change requests are integrated.
- Semantic Versioning is possible: GitVersion.
- This workflow stems from software development and has been proven for years.
- At LieberLieber, the workflow is used in collaborative modeling and software development.
- Book about Git: https://git-scm.com/book/en/v2
- GitVersion: https://github.com/GitTools/GitVersion
- GitFlow: https://datasift.github.io/gitflow/IntroducingGitFlow.html