4. Source Control

4.1. GitHub

The HLU Tool source code is hosted by GitHub in the HLUTool repository. GitHub is a well known web-based hosting service for software development projects. It uses the Git Version Control System (VCS) which, like all version control systems, records changes to a file or set of files over time so that specific versions can be recalled later.

If you are signed in to GitHub you can Fork the repository to create your own local copy, or alternatively you can download a Zip copy of all the source files.

4.1.1. Branches

There are two main branches in the HLUTool repository:

  • master : contains the source code for the ArcGIS/MapInfo variant of the tool

  • master-mapinfo : contains the source code for the MapInfo only variant of the tool

4.1.2. Commits

There are numerous commits to both of the above branches each of which incrementally contributes towards one of the releases for each variant of the tool. Each commit has a short summary and a longer text description of the changes that it contains and lists the files that were added/deleted/amended. Details of the actual lines added/deleted can also be viewed on GitHub.

New commits relating to changes to the tool in the future should similarly provide a summary and description of the changes, and ideally changes should be split/grouped where possible so that each relates to a single change or fix. This helps to determine what changes were made for each change/fix in the event that they need to be amended or reverted.

4.1.3. Tags

The source code for every version of the tool from v1.0.1 to v2.3.0 is Tagged on GitHub. The HLUTool Tags point to a specific ‘commit’ in a branch to indicate that the commit relates to a released version of the tool.

  • tags ‘v1.0.1’ thru ‘v2.3.0’ denote versions relating to the ArcGIS/MapInfo variant master branch

  • tags ‘v1.0.1m’ thru ‘v2.3.0m’ denote versions relating to the MapInfo only variant master-mapinfo branch.

4.1.4. Releases

In addition to the source code tags, each variant/version of the tool is listed under HLUTool Releases. Each release relates to one of the above tags, but in addition contains a set of Release Notes together with a download link to a Zip copy of the source code and the Windows Installer setup.exe program for that version. Links to the release for each new version can be sent to users of the tool for them to install.

4.1.5. Collaborating

Currently there are two owners of the HLUTool repository on GitHub, only one of whom is a developer. There has therefore been no need to fork the repository or raise Pull requests. If, in the future, a new developer is to take over development/maintenance of the tool then the simplest solution is for them to also become an owner of the repository so that they have control over source. However, if there is a need to have more than one developer then it may be necessary to agree on a collaborative source control process. According to GitHub there are two popular models of collaborative development:

4.1.5.1. Fork & Pull

The fork & pull model lets anyone fork an existing repository and push changes to their personal fork without requiring access be granted to the source repository. The changes must then be pulled into the source repository by the project maintainer (owner). This model reduces the amount of friction for new contributors and is popular with open source projects because it allows people to work independently without upfront coordination.

4.1.5.2. Shared repository model

The shared repository model is more prevalent with small teams collaborating on projects. Everyone is granted push access to the central, shared repository and topic branches are used to isolate changes.

Pull requests are especially useful in the fork & pull model because they provide a way to notify project maintainers about changes in your fork. However, they’re also useful in the shared repository model where they’re used to initiate code review and general discussion about a set of changes before being merged into a mainline branch.