This section describes a revision numbering strategy for the PAL software under the control of the Git and GitHub version control systems.

As stated previously, Git and GitHub use commit numbers to identify individual submissions to the repository, these are commonly referred to as hash or sha (pronounced shar to rhyme with bar) numbers. These are unique seven-digit hexadecimal numbers, and while they identify exactly, a particular revision within the repository, they do not do so in a way that can be easily interpreted by humans trying to understand the workflow of the project (given two commit numbers: [af25d47] and [9cf63b1], it would not be possible to say, just by looking at them, which came first), commit numbers can be considered completely random, but non-repeating numbers.

Git and GitHub both have the facility to tag any commit point, this tag must be unique, but it is entirely at the discretion of the user and can contain up to 25 characters.

The SCM numbering mechanism will use these commit tags to identify the particular revision of both a software module and a TIA Project.

The tags will also from the basis for naming the TIA Portal project at each commit point.

The workflow within the Git repository consists of a single main branch, the master branch.

The master branch (after some initial development work to establish it) will, generally, only contain either finished (released) modules, software that has passed some level of testing or qualification or software that has been released for use.

Released modules are modules that have undergone a software module test (SMT) and have passed that test (i.e. a module that is deployable) —it does not indicate that all software modules are finished, just that the module in question is complete, tested and deployable.

When the software as a whole (all modules), has completed module testing, integration testing, has been commissioned and qualified, then the software as a whole will be released for use.

Development work can take place at any time and will always take place on a separate branch. Development branches always spur from some definite commit point on the master branch.

A development branch must have a very restricted scope. I.e. a single module or group of related modules.

Generally, a development branch will contain all the things associated with that module (i.e. the function, any data types, data blocks &c.).

When the module development is complete and tested, it will be merged back to the master branch, the merge point will be given a five-character tag (Figure 3.1):

The project progresses through various different states along the master branch. Each state is a commit point and this in turn has a tag with five characters. Each such commit point is referred to as a primary commit.

Each primary commit tag is given a letter that represents the condition of a particular commit point.

	State	Example	Meaning	Description
	D	D0126	Development	The software as a whole is in the build phase and has not been fully tested. Certain modules may have undergone module testing and are released for use. This is on a module-by-module basis.
	P	P0001	Proving (test)	The software is released for integration testing. All modules within the software have undergone module testing and have been released for use.
	Q	Q0001	Qualification	The software is deployed for commissioning, installation qualification (IQ) and operational qualification (OQ).
	R	R0001	Released	The software is released for use
	Table 3.1   master branch commit point tags

The master branch commit tags have the following format:

SNNNN

Where S is the state letter (Table 3.1):

• D — Development

• P — Proving (testing)

• Q — Qualification

• R — Released

NNNN is a number; this starts at 0001 (there is a special case for the first commit to the repository, this has value 0000) for each particular state and is incremented by one for each subsequent issue.

E.g. D0001 → D0002 → D0003 → P0001 → R0001 → R0002 &c.

Generally, development never takes place along the master branch. The only exception to this is at the start of the project when the repository is created. The initial commit typically takes place on the master branch (this is always tagged D0000), and there may be subsequent commits on the master branch to establish the repository structure: folders, configuration files (e.g. .gitignore and .gitkeep files &c.) and other common repository files (README.md, LICENCE.md &c.), or to update some ancillary file information (e.g. README.md).

Such development can take place along the master branch until some suitable point is reached; this point is usually where module development begins; after this, only minor changes will take place on the master branch, such changes will be to address any conflicts that occur when merging multiple development branches back to the master branch (see Section 3.9).

At this point, no significant development work can take place on the master branch.

Development work always takes place on a separate development branch.

A development branch must have a very restricted scope. I.e. a single module or group of related modules.

Each development branch is taken from the latest primary commit point on the master branch (generally referred to as the HEAD). The name given to a development branch is always in the format:

SNNNNb-MMYYYYY

Where SNNNN is the commit point tag on the master branch from which the development branch diverges.

The b character is an ordinal character identifying multiple branches that start from the same master branch commit point, the first branch receives character A, the second B, the third C &c.

The remainder of the branch name refers to the object being developed; these are generally software modules. MMYYYYY specifies the object under development, for example FC01001. It could equally apply to just a data type e.g. UT01000.

Here, MM refers to the type of module (OB, FB, FC,DB, UT &c.) and YYYYY to the module number (these are always numerical, five-digit numbers with leading zeros where necessary)².

This arrangement can be seen below:

Here, two development branches diverge from the latest commit point on the master branch, point 1. The first branch is used to develop module FC01001, the second to develop module FC02001.

The first branch name takes the master branch commit point (D0002), followed by the ordinal character, since this is the first branch the ordinal character is A. Giving D0002A. This is followed by a dash (-) and the module number, in this case FC01001.

The final branch name is thus D0002A-FC01001. Point 2 in Figure 3.2.

The second branch is also attached to the master branch commit point D0002, but in this case it is the second branch, giving an ordinal character of B. In this case the module being developed is FC02001.

This gives a final branch name for the second branch of: D0002B-FC02001. Point 3 in Figure 3.2.

†2		Where some other type of change is being made, for example, standardising an arrangement of comment information across multiple blocks, the MMYYYYY format can be replaced with some more meaningful name e.g. UNIFICATION &c.

All development work takes place on the development branch. There will be many such branches through the course of the Project.

Each development branch will consist of multiple commits, these commits are referred to as secondary commits (c.f. primary commits made on the master branch). These secondary commits will mostly be incremental builds (an incremental build is just a point at which the work was committed to preserve the software at a particular point, these incremental builds occur often, allowing the software to be recovered if necessary. The reasons behind an incremental build are at the discretion of the developer, it may be a significant point in the development of the software, alternatively, it may be just a commit because it was the end of the day).

Each secondary commit on a development branch is tagged in the form:

SNNNNb-nnn.amm

Where SNNNNb is the first part of the branch name (before the dash), see § 3.3. This is the originating master branch commit point and the branch ordinal character.

The remaining characters (nnn.amm) are all numerical and reflect the current revision of the module under development, the details of this format are explained in Section 3.6.

The development branch will be complete when the module being developed on that branch has successfully undergone its software module test and the module is at a release revision, at this point the development branch can be merged back onto the master branch.

When all the work on a development branch is complete, that branch can be merged back onto the master branch.

Consider the following example:

Here a development branch (D0002A-FC01001) was initiated from master branch commit point D0002.

There have been three commits on the development branch: D0002A-000.101, D0002A-000.102 and D0002A-000.801; the first two were incremental builds and the last was a software module test. Let us assume that the module passed its module test and is now finished (released for use).

There will now be an additional (and final) commit on the development branch to reflect the released revision of the module:

The development branch can now be merged back to the master branch, following the merge, a new primary commit point must be created on the master branch. This will have a revised revision data for OB1 (see Section 3.7) and will have the format SNNNN.

This new commit point must be given the next, logical tag for the master branch. In this case, the last primary commit tag on the master branch was D0002, the next, logical primary tag is thus D0003 (an increment of one on the last master branch tag).

• Here, there is a transition from one development tag to the next (D0002 to D0003). It would be perfectly possible for this to be a transition to a different state, i.e. it could be going from development (D) to proving (P), in which case the numbering restarts at 0001.

Diagrammatically, this is:

Once the merge has taken place, all the secondary commits made on the development branch will become part of the master branch, thus:

Although the master branch now contains all the secondary commit point made on the development branch, none of them were made on the master branch itself (all this work happened on the development branch).

This arrangement is correct; ultimately, when the project is finished, there will only be the master branch left and this will contain every commit made within the project.

To more clearly understand the master branch, only the primary commit points (with just five characters) need be considered: