It is perfectly possible to have two (or more) simultaneous development branches:
Figure 3.24 Parallel development branches
This type of arrangement can appear slightly confusing when all the branches are merged back onto the master branch:
Figure 3.25 Merged parallel development branches
All the commits are listed in order of the time they were applied.
Things are simplified if only the primary commits are considered:
Figure 3.26 Merged parallel development branches, primary commits
From a workflow point of view, this is how the Project software should be viewed, a series of primary commits at which some part of the software was released for use.
The secondary commits are always present and can be recovered, however it is the primary commits that denote milestones in the software development.
With parallel branches, it does not matter what order the branches are made or what order they merge back to the master branch. In the previous example, D0001A is created first, and is merged back to the master branch first. The following shows a similar arrangement with the first branch merging last:
Figure 3.27 Parallel development branches with different merge order
Here, the second branch D0001B is created after D0001A but merges back before it; in this case the merged result would be:
Figure 3.28 Alternative Merged parallel development branches
And with just the primary commits:
Figure 3.29 Alternative Merged parallel development branches, primary commits
3.10
OB 1 and the Merging of branches
Where software development takes place on individual development branches, this will generally involve modules that have no relation to each other, in the example of Figure 3.24, the first branch develops a particular function (FC01001) and the second branch a completely different module (FC02001), these two modules (and their associated data blocks and UDTs) could be merged back to the master branch without issue, all the modules developed on the first branch have no connection with the modules on the second branch and vice versa; indeed, each branch has no knowledge of the modules being developed on the other branch.
This complete independence of modules on the different development branches means that there is generally, no conflict when the branches are merged, all the modules of the first branch can be merged to the master branch, and when the second branch is merged, it has a completely separate set of modules that can also be merged without conflict.
There is however, one problem with this: OB 1. OB 1 contains revision information for the whole project (see § 3.7) and both branches will have a modified OB1 and both OB 1s will be different; this will not cause a problem when the first branch is merged back to the master branch, all the changes were on the development branch and will merge back to the master without any conflict (referred to as a fast forward merge in Git terminology). However, when the second branch is merged back, there will be a conflict with OB 1 (because it has been changed on both branches) and there needs to be some mechanism for reconciling the differences.
To accommodate this, the following section describe how branches should be merged together and how the primary commits are generated.
There are two types of merge, the first is where the first (or a single) development branch is merged back to the master branch, this is the easier merge because there will be no conflict. The second type is where additional branches are merged back, this will cause a conflict with earlier merges and this is handled slightly differently.
Examining each in turn:
3.10.1
Merging a single branch or the first branch to merge
Consider the following example from the previous section:
Figure 3.30 Parallel development branches
For the moment, consider only the first development branch to merge back to the master branch: D0001A-FC01001:
At the merge point, the last commit to have been made on the D0001A-FC01001 branch was D0001A-001.000, at this point OB 1 had the following revision comments in it:
Figure 3.31 First branch merge OB 1 revision data
And the hardcoded revision was:
Figure 3.32 First branch merge OB 1 revision hard coded data
The merge will take place in Visual Studio Code (VSC) and will be made as a “fast forward” merge (this is the standard arrangement with VSC), this does not create a merge commit, it simple leaves the head at the last commit on the development branch.
After the merge, the master branch would be as follows:
Figure 3.33 master branch after first merge
As yet there is no final D0002 primary commit. This commit is made directly on the master branch after the merge.
This may seem to contradict the “no development work on the master branch” rule (see § 3.3); however, adding this primary commit point is simply updating the revision status of OB 1 and cannot be considered development work.
There are three changes to be made to OB 1, the first two are changes to the revision information (both hardcoded and in the network comments), the third is to the file name (§ 3.8.1).
The changes to the hardcoded OB 1 revision (in network 2) are to update the revision to the primary commit tag (in this case D0002), as follows:
Figure 3.34 Primary commit point hardcoded update
The update to the network comment requires the removal of the secondary commit information and the addition of the primary commit revision:
Figure 3.35 Primary commit point network comment update
The final change is to the TIA Portal project name in network 1 of OB 1:
Figure 3.36 Primary commit point project filename
Section 3.8 gives details of TIA Portal project names and their association with commit points.
3.10.2
Merging additional parallel branches
Again, consider the example given in the previous section:
Figure 3.37 Parallel development branches
In the previous section, the first branch D0001A-FC01001 was merged back to the master branch, leaving the overall workflow in the following state:
Figure 3.38 Parallel development after first branch merge
This is the point at which the second branch (D0001B-FC02001) is to be merged back to the master.
At this point, the last commit to have been made on the D0001B-FC02001 branch was D0001B-001.000. Figure 3.39 shows the OB 1 revision comments at this point.
It should be noted at this point that the OB 1 comments do not contain any information about the secondary commits on the D0001A-FC01001 branch or the D0003 primary commit point, this is because all those commits took place on other branches (either the D0001A-FC01001 branch or the master branch) and are at this stage unknow to the D0001B-FC02001 development branch.
Figure 3.39 Second branch merge OB 1 revision data
With the hardcoded revision:
Figure 3.40 Second branch merge OB 1 revision hard coded data
Again, the merge will take place in VSC and will again be made as a fast forward merge.
This will do two things, it will merge FC02001 on to the master branch with commit tag D0001B-001.000.
Secondly, it will indicate a conflict in OB 1, this is because OB 1 has been modified both on the D0001A-FC01001 branch (now merged to the master branch) and on the D0001B-FC02001 branch.
This can be seen in the source control state of Visual Studio Code (VSC):
Figure 3.41 VSC merge conflict indication
The commit hasn’t been made at this stage; this is because there is a conflict in one of the files.
This can be seen in point 1 in Figure 3.41, the affected files are listed under merge changes point 2, here it is just OB 1 that has a conflict (conflicted files are indicated by the red exclamation mark).
All the conflict free files (the ones that will merge without any issues) are showing as staged changes.
To allow the commit to take place, the OB 1 modifications will be discarded, this is done by right clicking the OB 1 file in merge changes point 2 in Figure 3.41 and selecting accept all current in the dropdown menu (the current being the current or, in this case the master branch).
The merge can now be committed, in this case with commit message D0001B-MERGE.
This will commit all the changes from the D0001B-FC02001 branch, but leave OB 1 as it was at the D0002 commit point, the list of commits on the master branch is shown below.
All the commits are there from both branches, the master branch has the following:
Figure 3.42 Merge intermediate commit
However, another primary commit now needs to be made on the master branch, this will be D0003, and this must include the updates made to OB 1, in the last commit on the D0001B-FC02001 branch.
This is similar to the changes made to OB 1 for commit D0002 (see § 3.10.1); it should be noted at this point that OB 1 is currently in the same state as it was at D0002, the last primary commit on the master branch
Again, there are three changes to be made to OB 1, the first two are changes to the revision information (both hardcoded and in the network comments), the third is to the file name (see § 3.8.1).
The changes to the hardcoded OB 1 revision (in network 2) are to update the revision to the primary commit tag (in this case D0003), as follows:
Figure 3.43 D0003 primary commit point hardcoded update
The update to the network comment requires the removal of the secondary commit information and the addition of the primary commit revision:
Figure 3.44 D0003 primary commit point network comment update
Finally, the TIA Portal project name in network 1 of OB 1:
Figure 3.45 D0003 primary commit point project filename
Other changes to OB 1 may be required, if additional information is stored (such as a summary of completed modules &c.).
3.11
Nested branches
It is possible to have a development branch from another development branch (referred to as nesting). Nested branches always merge back onto their parent branch:
Figure 3.46 Nested development branches
The nested development branch name has an extra character before the dash, this is another ordinal number, identifying the number of the nested branch. The rest of the branch name is as § 3.3:
SNNNNbX-MMYYYYY
The extra character (X) starts at 1 for the first nested branch and incremented by 1 for each additional nested branch.
Each commit on the nested branch has the format:
SNNNNbX-nnn.amm
3.12
A note on commit messages
Commit messages should have a short (less than 50 characters) first line. In Visual Studio Code (VCS), extended commits are possible (these are commits where more than one line can be entered), and the Commit Message Editor extension makes the configuration of commit messages into a standardised form-based format.
The Commit Message Editor is an extension for Visual Studio Code and can be found here: Commit Message Editor
The Commit Message Editor settings should be adjusted to match the following settings (these are stored in the settings.json file for Visual Studio Code):
settings.json
"commit-message-editor.tokens": [
{
"label": "Type",
"name": "type",
"type": "enum",
"options": [
{
"label": "---",
"value": ""
},
{
"label": "PS (Mas) - Dev",
"description": "PS master branch - development"
},
{
"label": "PS (Mas) - Merge",
"description": "PS master branch - merge point adjustment"
},
{
"label": "PS (Mas) - Prove",
"description": "PS master branch - proving (test)"
},
{
"label": "PS (Mas) - Qual",
"description": "PS master branch - qualification"
},
{
"label": "PS (Mas) - Release",
"description": "PS master branch - released for use"
},
{
"label": "PS (Dev) - Dev",
"description": "PS development branch - development"
},
{
"label": "PS (Dev) - Merge",
"description": "PS development branch - merge point adjustment"
},
{
"label": "PS (Dev) - Prove",
"description": "PS development branch - proving (test)"
},
{
"label": "PS (Dev) - Qual",
"description": "PS development branch - qualification"
},
{
"label": "PS (Dev) - Release",
"description": "PS development branch - released for use"
},
{
"label": "PS (Gen) - Rev",
"description": "PS development branch - revision update"
},
{
"label": "PS (Gen) - Type",
"description": "PS development branch - typographical changes only"
},
],
"description": "Type of changes"
},
{
"label": "Commit Tag",
"name": "scope",
"description": "The commit tag that will be applied to this commit (e.g. D0002B-0.101)",
"type": "text",
"multiline": false,
"prefix": "[",
"suffix": "]"
},
{
"label": "Commit Title",
"name": "description",
"description": "Commit title line text",
"type": "text",
"multiline": false
},
{
"label": "Body",
"name": "body",
"description": "Optional body",
"type": "text",
"multiline": true,
"lines": 10,
"maxLines": 100
},
// {
// "label": "Footer",
// "name": "footer",
// "description": "Optional footer: ",
// "type": "text",
// "multiline": false,
// }
],
"commit-message-editor.view.defaultView": "form",
"commit-message-editor.dynamicTemplate": [
"{scope} — {description}",
"",
"{type}",
"",
" ────────────────────────────────────────",
"",
"{body}",
" ",
" ────────────────────────────────────────",
"Those aspects of the PAL project that have been migrated to the GitHub",
"Version Control System (VCS) are operating under the Software Control",
"Mechanism (SCM) specified in document PS2001-5-2302-011:",
" https://practicalseries.com/2001-pal/31-git/11-00-scm.html"
],
Code 3.1 Visual Studio Code — Commit Message Editor settings
This arrangement gives a common form that can be used to enter and edit a commit message before making the commit. It has the following appearance:
Figure 3.47 Visual Studio Code — Commit Message Editor form
The type field is a dropdown selection that indicates the type of commit being made, those beginning PS(Mas) are commits directly on the master branch, those beginning PS(Dev) are on a development branch, those beginning PS(Gen) are of a general nature (not generally applicable to the software itself — e.g. a change to a README file or some file that is external to the Controller software).
The entry following the dash indicates the phase of the software as follows:
Entry
Meaning
Dev
Development commit (incremental build &c.)
Merge
Branch merge point
Prove
Proving (the software is at a test commit)
Qual
Qualification (the software is at a qualifying commit)
Release
Software (or module) is released for use
Rev
Revision change only
Type
Typographical corrections
Table 3.4 Commit message type field
The Commit tag is the commit tag that will be applied to the commit.
Commit Title is the first line of the commit, the first line is always shown in bold to indicate that it is a title.
The Body field contains the description of the changes being made at this commit point.
The completed commit has the following appearance:
Figure 3.48 Visual Studio Code — Actual commit message
