Practical Series Automation Library
4
The revision numbering mechanism and version control systems discussed in the previous sections was associated with the PAL software developed for the Siemens Controllers using TIA Portal and stored in the PS2001-pal-software GitHub repository (see Section 5.2 for details of the software and associated GitHub repository).
In addition to this repository, there is a second repository PS2001-pal-website that stores the website pages that are published in association with the PAL software (see Section 5.3 for details of the website and associated GitHub repository).
This website is also developed using the same revision numbering mechanism detailed in the previous section, there are however, some minor differences, particularly in the naming of branches. These differences are discussed in the following sections.
The website Git repository, like the software Git repository consists of a single main, master branch and various development branches.
The master branch (after some initial development work to establish the repository) will, generally, only contain released web pages
Released web pages are pages that have been built, tested and are complete and ready for live use on the website server.
As with the PAL software, development work can take place at any time and will always take place on a separate development branch and each development branch will spur from some definite commit point on the master branch.
With the website, each development branch has a very limited scope, usually the development of a single web page or series of webpages that are linked together (a section of the website for example). The branch may also be concerned with developing a background element of the website such as a particular JavaScript, jQuery or CSS file.
The website development progresses through various different states along the master branch in the same way as the PAL software (see § 3.2), where each state is a primary commit point. There are however, fewer states that can be applied to the website:
State | Example | Meaning | Description | |
---|---|---|---|---|
D | D0126 | Development | The website as a whole is in the build phase and has not been fully tested. Certain web pages may have been developed and tested and released for use. This is on a page-by-page basis |
|
P | P0001 | Published | The website is published for testing. All web pages within the software are present, and the site as a whole is being tested on a live website for consistency checks, final proof reading and link integrity. | |
R | R0001 | Released | The website is released for use/td> | |
Table 4.1 master branch commit point tags |
The master branch commit tags have the same format as the PAL software:
SNNNN
Where S is the state letter (Table 4.1):
D — Development
P — Published
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.
The main difference between the website workflow and the PAL software workflow is in the naming of development branches.
The website development like the PAL software development branches will always diverge from the latest primary commit point on the master branch. The difference is the name, the website development branch name is in the format:
SNNNNb-WW-PageName
Where SNNNN is the commit point tag on the master branch from which the development branch diverges and b is the ordinal character identifying multiple branches (this is identical to the PAL software in § 3.3).
The remainder of the branch name refers to the section of the website and the web page being developed. WW refers to the number main folder of the website (see § 5.3.2):
Folder | Purpose | ||
---|---|---|---|
00-comres | Common resources | ||
01-admin | Various administration pages | ||
11-web | The main website containing the PAL user guides and information | ||
21-project | Holds all the Project documentation (validation documents) | ||
31-git | Contains information used by the GitHub repositories | ||
81-binary | Contains binary files (the TIA Project archive files &c.) | ||
91-userdocs | The online version of TIA Project the User Documentation files | ||
Table 4.2 Website folder numbering |
I.e. WW will be 00, 01, 11, 21, 31, 81 or 91.
The PageName is the name of the HTML file for the particular page, an example being:
11-00-scm.html
This file (11-00-scm.html) is part of the 31-git folder of the website, hence the WW-PageName part of the branch name would be (don’t include the file extension):
31-11-00-scm
The PageName consists of a pair of number (11-00 in the above example) followed by a short description indicating the purpose of the web page (scm in the example). The number pair is always in the format cc-ss where cc is the “chapter” number of the web page and ss is the “section”. The web pages are assigned chapter and section numbers like a document (e.g. this part of this document is chapter 4, section 3; its web page equivalent would thus be 04-03).
The development branch is generally associated with a particular web page, and is named accordingly, however, the development branch will include all the files associated with, and required by that web page (i.e. the development branch will include the various CSS, JavaScript, jQuery, image files and binary files needed for the web page to work properly).
The index.html file associated with each of the main folders does not have any leading numbers in its file name (it is just called index.html), however, for the sake of consistency, such index files are given the numbe 00-00 in the branch name. E.g.:
31-00-00-index
Where the development branch is associated with a section (multiple pages) of the website, the branch name will use the chapter number only (just the cc part), for example, if a branch were developing the introduction pages of the website in the 11 web folder, its branch name would be:
11-01-intro
Where the development branch is for a particular file, rather than a web page (this is usually where a common file that affects the whole website is being change or created) then the branch name will have the format:
SNNNNb-00-FileName
The common files are always stored in the 00-comres folder (hence WW will always be 00), the file name is the name of the file being modified (without the extension) for example, if the main style.css file were being modified, the branch name would be:
SNNNNb-00-style
Development branch commit tags (secondary commits) are identical to those of the software development branches (§ 3.4); where each secondary commit is tagged and the tag has the format:
SNNNNb-nnn.amm
Where SNNNNb is the first part of the branch name (before the dash), see § 4.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 web page (or file) under development, the format of this revision number is similar to that of the PAL software and is explained in § 3.6.
The merging of development branches is generally a simplified arrangement of that used for the PAL software (see § 3.4 and § 3.5).
Development branches within the website are usually mutually exclusive and have no impact on each other (this is different to the PAL software where multiple branches usually have some degree of commonality, particularly with OB 1). This exclusiveness means that multiple branches can be merged without any conflict and the approach taken in § 3.5 for merging a single development branch or the first of multiple development branches can be adopted for all development branches within the website repository.
Exceptions exist where common table of contents (TOC) are being modified (and possibly where two simultaneous branches exist to modify a common file).
To minimise such conflicts, it is generally better to manage the workflow such that simultaneous (parallel) branches do not target common resources. Better to manage common files and common TOCs in a single development branch.
All the files associated with a web page (HTML, CSS, JavaScript and jQuery) have their own revision number. The current file revisions for all components of a web page are displayed at the top right of all web pages:
This can be seen in more detail below:
The Page revision data, point 1, shows the current revision of all the files associated with the particular web page.
The Common resources, point 2, shows the revision of the standard files that are common to all web pages.
Finally, the Global resources, point 3, shows the revision of all third party files (these are normalised revision generated within the project, i.e. project revision 001 of normailse.css reflects the actual file build of 8.0.1, the association between the normalised project build and the actual third party build is listed in the revision table at the start of each file).
The numbering of the webpage (or file) revision nnn.amm is an incremental numbering system. In this system nnn reflects the current version of the software; typically, the first properly released software will be 001. Previous development versions will be 000.
The numbers after the decimal point (amm) reflect development and test modification to the current revision (for software modifications), in this system a reflects the current status of the software as follows:
First digit (a) | Meaning | Description | |
---|---|---|---|
0 | Released mm will be 00 |
Page/file is released at version nnn (i.e. nnn.000) | |
1-7 | Development | Page/file is under development and has not been tested | |
8 | Publication | Page/file has been published (on the webserver) for live testing/td> | |
Table 4.3 Website revision number (first digit) |
The remaining numbers (mm), are incremental build numbers for the current revision (this allows development tracking).
The Global resources revisions, point 3, in Figure 4.2 only have the first three digits (nnn), third party software is always at a released version.
All HTML, CSS, JavaScript and jQuery files have a modification history at the start of the file; an example for style.css is shown below:
In addition, the revision information is also hardcoded into each file:
The various revisions for each file type are displayed by the HTML as multiple rows in a revision table, the following shows the format of each entry:
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ TABLE - REVISION TABLE ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --> <table class="table-rev"> <!-- Data row --> <tr> <td class="leading" style="height: 1em"></td> <td class="table-cent" style="width: 30%"></td> <td class="table-left" style="width: 40%">NAME:</td> <td class="table-right" style="width: 30%" id="ID_NAME"></td> </tr>
The NAME and ID_NAME are as follows:
NAME | ID_NAME | Description | |
---|---|---|---|
Page | rev-doc | Hardcoded revision of the web page | |
scroll.js | rev-scroll | ID_NAME is replaced by the revision number in NAME file | |
codelines.css | rev-codelines | ||
script.js | rev-script | ||
style.css | rev-style | ||
style-pal.css | rev-style-pal | ||
grid.css | rev-grid | ||
ps-fonts.css | rev-ps-fonts | ||
normalise.css | rev-normalise | ||
lightbox.css | rev-lightbox | ||
waypoints.css | rev-waypoints | ||
hyphenator.css | rev-hyphenator | ||
ionicons.css | rev-ionicons | ||
prettify.css | rev-prettify | ||
prettify.js | rev-run-prettify | ||
Table 4.4 NAME and ID_NAME associations |
Each file listed in the NAME column appends its own revision number to the ID_NAME HTML ID value, in the case of style.css, the code is:
/* **************************************************************************** REVISION **************************************************************************** */ #rev-style:after { content: "000.102"; }
In the case of a .js file, it has the following appearance (this is for script.js)
/* **************************************************************************** REVISION **************************************************************************** */ $('#rev-script').append ( "<p>000.101</p>" /* LOCAL JS REVISION NUMBER */ );
The actual HTML file has the data hardcoded in the HTML table after the rev-doc ID (000.101 in this case):
/<!-- Data row --> <tr> <td class="leading" style="height: 1em"></td> <td class="table-cent" style="width: 30%"></td> <td class="table-left" style="width: 40%">Page:</td> <td class="table-right" style="width: 30%" id="rev-doc">000.101</td> </tr>