Skip to content

Version Control Procedures

Abstract

This chapter explains the version control procedure enforced by the punchplatform team and tools.

Overview

The overall principles of PunchPlatform configuration management are explained in version control`, to be read first.

For clarity this chapter provides some insight on the use of the version control git tool. We strongly recommend the reading and understanding of git concepts and commands, refer to the Git documentation

Git concepts

git tags

Tags are used to mark/identify a past status in a git repository. In PunchPlatform configuration management tags are use to unabiguously refer to a precise release. For example tag '5.6.0'.

Note

a tag stores not only the current state of all files in the filesystem, but also the state of the list of all successive changes that have been made previously (the 'git log') to arrive at this point.

git branches

A branch is a working space that is used by one or several users to commit new changes. It can be seen as a 'floating tag' that is automatically updated each time one of the team members pushes a modification to it. This way, one of the team member can easily retrieve the "last status" of this working space.

In PunchPlatform team daily work, the following branches are used :

  • major release common development branch. (e.g. '5.x'). These branches are used for integrating new developed features, and running integration tests. They normally contain all developed features, as soon as the developer has satisfied basic stability criteria (unitary tests, documentation update, non-regression test on a standalone environment).
  • feature development branch (e.g. '5x-pp3567-new-security-authent'). These branches are temporary work space for one or more developers working on the same feature. There is no stability constraint on this versions, except if mutually decided by the co-workers using the branch
  • local workspace. IMPORTANT : Because of its distributed nature, any developer work space is in itself an 'implicit' branch separated from the workspaces of other developer computers (even tough it has the same git branch name as on other computers). To allow merging of multiple people work, the team git server is used as a storage space into which common work reference is stored. Each developer has to merge/test on his computer the work of the team with his new local changes, and then update the team git server with the result.

git merge

Action of bringing into the working git branch, some changes coming from an other branch, or from any repository state (tag) that includes changes not yet imported in your working branch state.

When merging, git tries to find which "common" version existed in the past (git log) of YOUR branch and the past of the imported branch or tag. Then git tries to determine if changes made since this command on your branch and the imported context can be merged automatically (for example, changes made on different sections of the same file). If not, the user will have to manually analyze this changes to decide what the final 'merged' version of the file should look like.

Version Control Procedures

Developing a feature on multiple major releases

Why Do That ?

  • I have to develop a new feature.
  • I am a member of the puch development team allowed to integrate features in the coming major release.
  • Two major releases are currently maintained with non-frozen feature scope : 5.x, and 6.x
  • The team designers have agreed that this feature can and must be developed so as to be compatible with both releases.

Procedure

  • Clone the development repository pp-punch.
  • Checkout the latest stable state of the common development branch (to be done in each of the repositories): :
git checkout 5.x
  • Create a feature branch to work independently on common branch, in order to avoid its unstabilization :
git checkout -b 5x-pp6787-my-new-feature
  • (Repeatedly) do some changes on files, and commit and secure your changes by storing them on the team git server :
git add <files....>
git commit -m "<Comment including the reference to the #<number> of the jira (or formerly redmine) issues associated to the feature or fix>"
git push origin feature-my-new-feature
  • After having reached a stable status of the feature (unit tests OK, updated product documentation, some non-regression testing done at standalone deployment level at least), integrate your feature inside the common development branch of the major release :
git checkout 5.x
# to retrieve last changes of the team from the team git server
git pull origin 5.x
# git checkout 5x-pp6787-my-new-feature
git merge 5.x
# resolve any conflicts
git mergetool                
git commit
# And, after retesting stability of the integrated version
git push origin 5x-pp6787-my-new-feature
# All done you can submit your merge request
  • Prepare for merge of the new Brad development into Craig major release. this needs to insure all merged artifacts are NON-SNAPSHOT to ensure unicity of maven artifacts version in a multiple-releases context :
pp-core/poms_housekeeper.sh --release    # To remove 'snapshot' status marker to all maven artifacts versions
pp-core/poms_housekeeper.sh --check

vi pp-core/RELEASENOTE.rst # ensure that all issues that have been merged into Ahmad-dev are listed in the description rubric of the currently being integrated ahmad version
cd pp-core
git add RELEASENOTE.rst
cd ..

for repository in pp-core pp-log-resources pp-packaging ; do
    cd ${repository}

    git add ./*.pom.xml     # to add all modified maven .pom files
    git commit -m 'Releasing artifacts'
    git push origin ahmad-dev

    cd ..
done
  • Merge into Art common development branch TO BE REPEATED for each repository (pp-core, pp-log-resources, pp-packaging) : :
cd pp-core
git fetch origin art-dev
git fetch origin ahmad-dev
git checkout art-dev
git merge ahmad-dev
git mergetool           # here, you may have to solve manually conflicts

# EDIT and update all .pom files of artifacts that have been modified by merge, in order to increment
# version of artifact, and report development status by appending '-SNAPSHOT' to the maven version
# This can be done recursively by the script '../pp-core/poms_housekeeper --middle-increment --snapshot <path to pom>' so as not to forget any indirect modification of dependent PunchPlatform artifacts.
  • And, after retesting stability of the integrated versionCheck stability of locally integrated version, commit merged major release to the team git server : TO BE REPEATED for each repository (pp-core, pp-log-resources, pp-packaging) : :
git commit
git push origin art-dev

Developing a non-urgent maintenance fix on a production-deployed major release version

Why Do That ?

  • A bug has been diagnosed on version Ahmad V2.1.2, which is deployed at a customer site
  • The last stable version of Ahmad is V2.1.3.
  • No migration issue is identified in the release notes preventing a migration from V2.1.2 to V2.1.3 requiring any change in customer site configuration. The PunchPlatform maintenance team therefore decides to build the fix to be compatible with the major release Ahmad.
  • The bug is not of critical nature, so that it looks possible to release a new version of Ahmad including both the required fix, and the new features or other fixes that have been integrated in the ahmad development branch.

Procedure

  • Clone the development repositories :
  • Request production-site state of common development branch for Ahmad major release (to be done in each of the repositories): :
git fetch origin --tags   # to retrieve all tags definition from reference git server
git checkout AHMAD_V2_1_2  # use git tag --list if you need to check existing version tags
  • Create a 'fix development branch', first to reproduce the bug in a site-identical version, then to develop fix :

git checkout -b feature-my-ahmad-bug-fix
- Generate the version and reproduce the bug with it - Develop the bug fix in your fixing branch by (repeatedly) do some changes on files, and commit and secure your changes by storing them on the team git server :

git add <files....>
git commit -m "<Comment including the reference to the #<number> of the jira (or formerly redmine) issues associated to the bug>"
git push origin feature-my-ahmad-bug-fix
  • After checking the bug if fixed , and having reached a stable status of the fix (unit tests OK, updated product documentation, some non-regression testing done at standalone deployment level at least), integrate your feature inside the common development branch of the major release as decided by the maintenance team :
git fetch origin ahmad-dev  # to retrieve last changes of the team from the team git server
git checkout ahmad-dev
git merge feature-my-ahmad-bug-fix
git mergetool                # if some merge could not be made automatically by git
git commit
# And, after retesting stability of the integrated version
git push origin ahmad-dev

Developing an urgent maintenance fix on a production-deployed major release version

Why Do That ?

The context is the same as for [Developing a non-urgent maintenance fix on a production-deployed major release version], except that the team prefers to release a new version of Ahmad major release without taking into account the new ahmad features and other fixes that had already been prepared in ahmad-dev common development branch.

The fix will of course have to be also integrated in subsequent Ahmad updates that will include these new features...

Procedure

  • Clone the development repositories : :

    1
    2
    3
    git clone https://git.gp.sef.cloudomc.ts-agora.fr/punchplatform/pp-core
    git clone https://git.gp.sef.cloudomc.ts-agora.fr/punchplatform/pp-log-resources
    git clone https://git.gp.sef.cloudomc.ts-agora.fr/punchplatform/pp-packaging
    
  • Request production-site state of common development branch for Ahmad major release (to be done in each of the repositories): :

    1
    2
    git fetch origin --tags   # to retrieve all tags definition from reference git server
    git checkout AHMAD_V2_1_2  # use git tag --list if you need to check existing version tags
    
  • Create a 'fix development branch', first to reproduce the bug in a site-identical version, then to develop fix :

    1
    git checkout -b feature-my-ahmad-bug-fix
    
  • Generate the version and reproduce the bug with it

  • Develop the bug fix in your fixing branch by (repeatedly) do some changes on files, and commit and secure your changes by storing them on the team git server :

    1
    2
    3
    git add <files....>
    git commit -m "<Comment including the reference to the #<number> of the jira (or formerly redmine) issues associated to the bug>"
    git push origin feature-my-ahmad-bug-fix
    
  • After checking the bug if fixed , and having reached a stable status of the fix (unit tests OK, updated product documentation, some non-regression testing done at standalone deployment level at least), follow Releasing major version for delivery procedure to produce a new ahmad release version and provide the associated distribution packages to the customer site for deployment BUT package, test tag the AHMAD_V2.1.3 fixed release directly from the [feature-my-ahmad-bug-fix] branch, instead of doing it from the [ahmad-dev branch] (as is described in the generic [releasing major version for delivery] procedure )

  • Integrate the new fix in the Ahmad release versions yet to come (to be repeated in all pp-core, pp-log-resources and pp-packaging git repositories) :

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    git fetch origin ahmad-dev  # to retrieve last changes of the team from the team git server
    git checkout ahmad-dev
    git merge feature-my-ahmad-bug-fix
    git mergetool                # if some merge could not be made automatically by git
    
    ## edit maven .pom files and RELEASENOTE.rst to increase the version number of PunchPlatform packaging artifacts to match next version to come (Ahmad V.2.1.5-SNAPSHOT).
    git add RELEASENOTE.rst # this, of course just in pp-core
    git add ./*.pom.xml
    git commit
    # And, after retesting stability of the integrated version
    git push origin ahmad-dev
    
  • The team can go on developing the next version of ahmad release...

Developing my own additions to the PunchPlatform product, without being a team member

Why Do That ?

  • I want to prototype/develop a feature in addition to last PunchPlatform stable release
  • I am (not yet?) a member of PunchPlatform development team allowed to integrate features in the coming major release.
  • I do not want to be bothered by new features being integrated by the main PunchPlatform development team for the coming next major release version.

Procedure

  • Clone the development repositories : :

    1
    2
    3
    git clone https://git.gp.sef.cloudomc.ts-agora.fr/punchplatform/pp-core
    git clone https://git.gp.sef.cloudomc.ts-agora.fr/punchplatform/pp-log-resources
    git clone https://git.gp.sef.cloudomc.ts-agora.fr/punchplatform/pp-packaging
    
  • Request last state of stable major release (to be done in each of the repositories): :

    1
    2
    3
    4
    git checkout craig  # This tag retrieves last stable,maintained version of the craig major release.
    # Alternatively, you can do 'git checkout craig-stable', but you will not be able to ciommit changes in this branch : it is dedicated to holding only official PunchPlatform distributions (see `Releasing major version for delivery`_)
    
    # At this step, you have everything to build PunchPlatform and run it !
    
  • Create my personal work branch, to avoid mixing my development with someone else... :

    1
    git checkout -b my-own-work-space-branch
    
  • (Repeatedly) do whatever you want to code, test... and commit it on PunchPlatform team git server to secure your development and ease its integration in future releases of punchplatform :

    1
    git push origin my-own-work-space-branch
    
  • call us so that we know about your work, and discuss integrating it in next release !

Releasing major version for delivery (or internal version, for integration purpose) {#Releasing major version for delivery}

Example context

The team has integrated a set of features and fixes in a common development branch for one of the punchplatform major release (Ahmad) We want to package and deliver the PunchPlatform distribution to the outside world, and to maintain it afterwards. This new version will be called Ahmad V2.1.6

Procedure

  • After having reached a stable status of the development branch (unit tests OK, feature tests OK, updated product documentation, migration procedure testes, non-regression testing done at standalone deployment level at least), :

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    git fetch origin ahmad-dev
    git checkout ahmad-dev
    
    pp-core/poms_housekeeper.sh --snapshots-check <PREVIOUS_RELEASE_TAG> # this allows to detect any artifact which version should have been snapshotted because of file changes since the last version
    (use  pp-core/poms_housekeeper.sh --snapshot if there are some inconsistencies)
    
    pp-core/poms_housekeeper.sh --release    # To remove 'snapshot' status marker to all maven artifacts versions. This needs to be done once only because it will apply to all the PunchPlatform git repositories.
    
    pp-core/poms_housekeeper.sh --check
    
    vi pp-core/RELEASENOTE.rst # ensure that release note includes all information about the version (including new features numbers, fixed bugs numbers, known bugs numbers, migration documentation reference)
    
    cd pp-core
    git add RELEASENOTE.rst
    cd ..
    
    for repository in pp-core pp-log-resources pp-packaging ; do
        cd ${repository}
    
        git add ./*.pom.xml     # to add all modified maven .pom files
        git commit -m 'Releasing artifacts'
        git push origin ahmad-dev
    
        cd ..
    done
    
  • REBUILD the version (this IMPORTANT step will generate among other things the PDF documentation, to ensure it can be built, because it is deactivated when building a SNAPSHOT version)

  • Proceed to validation tests on this rebuilt version (standalone redeployment, integration tests...)
  • Tag this version as an official one ( to be repeated in each of the pp repositories) - if the version is to be for internal use only (at least temporarily) then the tag should be AHMAD_INTERNAL_V2_1_6 instead : :

    1
    2
    git tag "AHMAD_V2_1_6"
    git push origin AHMAD_V2_1_6 --tags
    
  • Tag this version as the last stable one (in each of th pp repositories) :

    1
    2
    git tag "AHMAD" --force    #This updates the "AHMAD" tag to register this new version as the last
    git push origin AHMAD_V2_1_6 --tags
    
  • (Alternate to (re)defining floating tag "AHMAD") Update the main branch of the major release, that only contains official stable versions of the release : :

    1
    2
    3
    4
    git fetch origin ahmad-stable
    git checkout ahmad-stable
    git merge AHMAD_V2_1_6
    git push origin ahmad-stable
    
  • Ensure you have rebuild locally on your station all the artifacts, then deploy new release artifacts to the release repository :

    1
    pp-core/poms.housekeeper.sh --deploy-from <previous release tag>
    

    where identifies the last deployed release artifacts bundle (for example : AHMAD_INTERNAL_V2_1_5). This will identify all maven artifacts that have increased their version number between the previous release and the new one, and will deploy the release artifacts to the LMC Software Engineering "Releases" repository

  • Publish the development documentation :

    : connect to jenkins builder, and run the "dev-doc-publishing" job, : :

    1
    2
        gittag = AHMAD_V2_1_6
        productbranch = ahmad
    
  • Publish the product documentation and download links (NOT FOR INTERNAL RELEASES) :

    : connect to jenkins builder, and run the "product-doc-publishing" job, : :

    1
    2
        gittag = AHMAD_V2_1_6
        productbranch = ahmad
    

    This will publish the distribution documentation and packaging URLs in the PunchPlatform documentation site.

  • IMPORTANT : re-snapshot the development repositories to avoid accidental local regeneration of new artifacts content with the same version number :

    : cd pp-core ./poms_housekeeper.sh --snapshot punchplatform-doc/pom.xml ./poms_housekeeper.sh --snapshot ../pp-log-resources/pom.xml

    1
    2
    3
    4
    5
    6
        # EDIT RELEASE NOTE to create a new "-SNAPSHOT" version section a top of document
    
        # And for each of the repositories :
        git add .
        git commit -m "snapshotting for next release"
        git push origin art-dev
    
  • Manage your tickets in your ticketing tool: close tickets, create the new version

Rename all pom.xml

find . -type f -iname 'pom.xml' -exec sed -i 's/5.0.1-SNAPSHOT/5.1.0/' "{}" +;