This section describes a revision numbering strategy for a website development project under the Git and GitHub version control systems.
Git and GitHub use commit numbers derived from the checksum of files being added to the repository. These appear at best to be seemingly random seven digit hexadecimal numbers. They do not represent a meaningful number that is useful for team members trying to identify a revision path.
Git and GitHub allow any commit point to have an associated tag, this is entirely at the discretion of the user and (other than the requirement of being unique) can be anything at all.
This allows each commit point to be tagged with a more meaningful (semantic) version number. Something that makes sense to humans.
The following is a proposed mechanism for just such a workflow and tagging arrangement.
B.1
Workflow arrangements
The workflow consists of a single main branch, the master branch.
The master branch (after some initial development work to establish it) will only contain either finished publishable work or a completed and released website.
Publishable work is a section of the website that is complete in itself—it does not indicate that the whole website is finished, just that the section in question is complete, tested and deployable.
A website release indicates that the whole website is finished. Release R01 will be active when the entire website and all its pages is published for the first time.
Development work can take place at any time and will always take place on a separate branch. Development branches always spur from some published or released point on the master branch.
A development branch must have a very restricted scope. E.g. a single section of the website (or just a page).
Generally, a development branch will contain all the things associated with that section: html, js and css files as well as associated images and data.
When the development is complete and tested, it will be merged back to the master branch, the merge point will be a published or released commit (Figure B.1):
Figure B.1 master branch workflow
B.2
Master branch revisions
The project progresses through various different states along the master branch.
Each state is given a letter that represents the condition of a particular commit point.
State
Example
Meaning
D
D02
Development
The site is entirely under development and no part of it has been published
P
P04
Published (partial)
Partial publication—certain pages of the website are finished and have been published
R
R01
Released
Released—all pages are complete and the whole site is finished
Development can take place along the master branch until some suitable (publishable) point is reached.
At this point the site has been published, the site might not be complete (with the Practical Series Web Development site I tended to write a section, test it and then publish that section), but no further development work can take place on the master branch.
This leads to the website being developed and published in stages; however, any code on the master branch at a published or released commit point must be finished, fully tested, working and deployable.
Development work always takes place on a separate development branch. Each development branch is taken from the latest published or released version of the software on the master branch. The name given to a development branch is:
d-XX-name
Where d- indicates the branch is for development (all my branches are development branches and always start with d-).
XX refers to the number of the web page or section being developed. For example, the PS Web Development is split into sections and each section is given a two digit number. It starts like this:
00-index and common files—css/fonts &c.
01-introduction
02-fairfax
03-grid
In Figure B.1 the first development branch is called d-99-typicals. This is a page that contains an example of all the possible sections, headings, tables, images and advanced functions such as code fragments, formulae and lightbox imagery.
It is a good starting point for any other page that may be required and it makes sense to develop this page first.
All the development work takes place on the development branch. There will be multiple commits made on this branch; these will mostly be incremental builds (an incremental build is just a point at which the work was committed, the work wasn’t finished; I may just have committed the code at that point because it was the end of the day).
Each development commit on a development branch is tagged, and the tag has the format:
d-SNN.XX.YY
Where SNN is the state of the commit point on the master branch when the development branch was created (i.e. the parent commit point to which the branch is linked).
XX refers to the number of the web page or section being developed (this is the same as the XX in the branch name, see above).
YY is a number starting at 01 and is incremented by one for each commit along the branch.
Once the code has been developed, it progresses to a test stage; this takes place along the same branch. The commit tag changes however, it now becomes:
t-SNN.XX.YY
It is now preceded by a t- instead of a d-. The number YY continues at the next number following the last development commit when the test stage starts. This allows tested code to drop back into development. The following sequence illustrates this:
Finally, at the end of testing, the code is finished and is ready to be merged back into the master branch. At this point, a new commit point is made on the branch. This is referred to as a Staged commit. It again has a tag and this time the tag format is:
s-SNN.XX.SNN+k
The s- indicates a staged commit. SNN.XX is exactly the same as each other commit on the branch.
SNN+k indicates the new merge commit point on the master branch that will be created when the development branch is merged onto the master branch. I.e. the point at which the branch re-joins the master.
Normally, this will just be a the SNN value plus one (it may be more if other branches are involved, it will always be the next publication or release commit number on the master branch, see § B.4).
In Figure B.2, the development branch d-99-typiclas split from the master branch at commit point P01 (SNN is P01). After the development process, the code is ready to merge back onto the master branch. The next publication commit point on the master branch will be P02 (NN goes up by 1). So the last staged commit on the development branch will be s-P01.99.P02.
Figure B.2 development branch workflow
The final commit on the development branch, the staged commit (s-P01.99.P02 in this case) is done to allow the software versions of each file to be changed to match the forthcoming master branch commit (P02 in this case). The code itself shouldn’t change, just its revision status.
There is only ever one staged commit on a development branch.
For smaller development branches, it is not necessary to have the staged commit; it can be done with the test commit. In this case, the test commit would have the form t-SNN.XX.SNN+k—this is exaclty the same structure as a staged commit tag, but prefixed t- instead of s-.
B.4
Parallel development
It is perfectly possible to have two simultaneous development branches:
Figure B.3 Parallel development branches
With parallel branches, it does not matter what order the branches are made or what order they collapse, here d-01 is created first, but d-02 is merged back into the master before it.
This type of arrangement can appear slightly confusing when all the branches are merged back onto the master branch, it looks like this (I’ve coloured the tags with the appropriate branch colour):
Figure B.4 Merged parallel development branches
It makes sense if you think about it; commits are listed in order of the time they were applied.
B.5
Nested development
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 B.5 Nested development branches
The second development branch is called da-<as parent branch>. The third would be called db-<as parent branch>, da, db, dc &c.
Each commit on the nested branch has the format:
d/t/sL-SNN.XX.ZZ
Where L is the branch identifier (a, b, c, &c).
SNN-XX is identical to the parent branch (master branch commit and web page or section number).
ZZ is a number starting at 01 and is incremented by one for each commit along the nested branch.
Nested branches can have test revisions (ta, tb, tc, &c.) and a staged commit (sa, sb, sc &c.).
The staged commit reflects the merged commit number on the parent branch. There is only one staged commit per nested branch.
B.6
A note on numbering
All the numbering I’ve shown in this section has been two digits d-P01.03.05. This clearly limits any revision, page or section number to a maximum value of 99.
This needn’t be the case; it is perfectly possible to use three digit numbers d-P001.003.005, indeed this could be selectively adapted: d-P01.0103.005, you can do whatever you like.
I think the two digit version is enough for me. If I’ve got more than 99 commits on a development branch I’m probably doing it wrong.
I can see the advantage in having a four digit middle number d-P01.0103.05, it would allow me to resolve to individual web pages; however, I nearly always develop a full section at a time. I write it in Word and then encode it in HTML.
I suggest you start with the two digit version and see how you get on.
B.7
A note on commits
Commit messages should have a short (less than 50 characters) first line. In Brackets, where extended commits are used, always leave a blank line after the first line (this ensures the first line is treated as a title).
Always include the status of the commit in the title:
D — Development
P — Published (partial)
R — Released
Generally keep the remaining lines short (less than 75 characters).
Within the commit message list every file that was altered in the commit (list them separately on each line).
When closing issues with commits (see § 10.2.5) provide a separate line within the commit message indicating which issue was closed and why (don’t put all the close command in the title line); e.g.:
