Code Versioning
Working on projects with multiple collaborators and large volumes of files can become very difficult – especially because people can change the same files. Code versioning tools allow us to manage changes to files giving the ability to compare, restore and merge revisions done on files.
We understand that you’re a new and learning how to take advantage of code versioning systems such as Git and CVS is difficult and has a fairly steep learning curve. We recommend that before you begin you should research some visual tools such as sourceTree for MacOSX or tortoiseGit for Windows – this makes life easier and you can see exactly what is happening before you take on the scary terminal!
These files are NOT allowed in repositories and should be managed within the .gitignore file at the root of the repository. Changes to binary files give versioning systems a very hard time to manage and usually results in large differences between commits and therefore a larger footprint for each commit. Allowances should be made for static binary files necessary in the code project such as images or videos. In a python the following files should be included in the .gitignore file (https://github.com/CodeForTheCaribbean/HarvestAPI/blob/master/.gitignore).
Each developer is responsible for managing his/her library files (for python based projects). The lib/ and lib64/ folders are by default excluded from the repository. Also with the pip package manager, this is usually an automated process as long as a requirements file is present in the repository and actively maintained.
This is essential for the documentation of versions throughout the project’s history (GIT 2014). Like most VCSs, Git has the ability to tag specific points in history as being important. Typically people use this functionality to mark release points (v1.0, and so on). The creation of an annotated tag can help with the generation of change release notes. These notes document the changes to the project between versions.
Creating an annotated tag in Git is simple. The easiest way is to specify -a when you run the tag command:
$ git tag -a v1.4 -m 'my version 1.4'
$ git tag
v0.1
v1.3
v1.4
The -m specifies a tagging message, which is stored with the tag. If you don’t specify a message for an annotated tag, Git launches your editor so you can type it in (recommended).
At the core, the development model is greatly inspired by existing models out there. The central repo holds two main branches with an infinite lifetime:
-
master
-
develop
The master branch at origin should be familiar to every Git user. Parallel to the master branch, another branch exists called develop.
We consider origin/master to be the main branch where the source code of HEAD always reflects a production-ready state. When the source code in develop is deemed stable it should be merged back into master, tagged with the release number and a nice detailed message describing the changes between the previous production release and the current one. This is VERY important, so that theoretically, we could use a Git hook script to automatically build and roll-out our software to our production servers every time there was a commit on master.
**Figure 1 - Basic Git Model **
Merging is Git's way of putting a forked history back together again. The git merge command lets you take the independent lines of development created by git branch and integrate them into a single branch.
Firstly before proceeding we must define the various branches and their definitions in the context of software development:
-
master – This is seen as the production ready branch. Any changes done to this branch will include new features and fixes to correct security vulnerabilities and bugs.
-
develop – This is the main branch where new features are integrated and tested. All tests must be performed here before merging into production ready branch (master).
-
feature – This is a branch off develop and is usually treated as a supporting branch and is used to develop new features for the upcoming or future releases. In the case of experiments this is important as failures can be easily discarded without affecting develop.
-
hotfix – This is another supporting branch of master and is used in emergency cases where critical and severe bugs are quickly corrected and put back into production. The hotfix MUST also be incorporated into develop to prevent undoing changes to master at the time of committing a new feature.
As you can tell, there are several reasons to merge branches. Some of the main reasons:
-
The engineer has completed a new feature and wants to incorporate it back into the code base. He/she would merge the feature branch back into develop, for future compliance checks and eventual incorporation into the production release.
-
A severe/critical defect has been corrected in a hotfix branch and it is necessary to move it back into production and develop.
-
An experiment went well and has been approved to be a part of the project by a senior engineer.
The technical details about merging are further described by Atlassian at https://www.atlassian.com/git/tutorials/using-branches.
Figure 2 - More complex Git model (usually as the project evolves and team increases in size) (Driessen 2010)
Since the master branch is denoted as the production-ready branch, it is necessary to have a high level of control over the merge request to this branch. The acceptance of the merge request is pending an acceptance testing of the code-base by a senior engineer, done on an infrastructure similar to that of the production environment.
This step again is necessary especially if there are hooks to the master branch of the repository allowing for automated deployment into production. A mistake here can be devastating to mission critical applications and especially damaging if there are established service-level agreements (SLA).
In the acceptance testing the software is checked against requirements and specifications to determine if the software successfully conforms. If the software is rejected, the senior overseeing engineer or project owner must make a list of reasons and suggestions to the developer(s) involved. A request may be rejected if it conflicts with:
-
Project road map
-
Business requirements
-
Bugs or issues with code-base
-
Poorly documented code
-
Security Vulnerabilities
-
UX/UI issues
-
Deprecation Violations
-
Architectural Issues
-
Copyright Infringement(s)
-
Proprietary Software Package Usage
-
IP Violoations
