7. New Releases

7.1. Building the Tool

When building the tool for a new version/release, rather than for just testing or debugging changes in progress, there are a number of steps to follow or dependencies to consider.

7.1.1. Version Numbers

7.1.1.1. Assembly version

The HLUGISTool assembly version, using the format Major.Minor.Patch.Build, should be incremented following semantic versioning rules. So whether the increment relates to a major change, minor update or just a patch will depend on what is contained in the new release.

  • Major version numbers change whenever there is significant change to the look or functionality or for large or potentially backward-incompatible changes.

  • Minor version numbers change when a new minor feature is introduced, or when a set of smaller features are rolled out together.

  • Patch numbers change when a new build of the software is released containing small bug fixes.

  • Build numbers typically don’t change as a new version is not usually released just for a new build.

Note

The assembly version number appears in the ‘About’ pop-up window on user interface.

7.1.1.2. Product version

The product version in the installer project properties should also be changed to match the assembly version number.

Note

The installer product version number is used when installing the tool to ensure an older version of the tool doesn’t overwrite a later version. The version number also appears in the Control Panel Programs and Features list.

7.1.2. Product Code

The installer Product Code should be changed to uniquely identify this version if the product. The Windows installer uses the product code at run time to determine whether the same version of the product has already been installed.

Note

To create a new GUID that uniquely identifies a new version of the product or click the Generate a new GUID button ({…}) in the Product Code setting in the General Information tab of the InstallShield project.

A note of all previously used Product Codes is maintained in ‘Releases and Product Codes.txt’ in the source code repository on GitHub.

7.1.3. Upgrading

The installer Upgrade From Max Version must reflect the version number of the most recent release so that the Windows installer will find and upgrade all previous of the tool.

7.1.4. ReadMe files

The ReadMe file must be amended to reflect the version number and copyright details of the new release, as well as any new features or changes to system requirements. The ReadMe file is maintained in three different formats; simple text (.txt), rich text (.rtf) and markdown (.md). Each format is used in different circumstances:

  • ReadMe.txt - Installed with the tool on the target system.

  • ReadMe.rtf - Displayed during the installation process.

  • ReadMe.md - Displayed in the source code repository by GitHub.

7.2. Distributing the Release

The tool is currently distributed via GitHub. There are a number of stages involved in distributing a new release of the tool.

7.2.1. GitHub Tags

Once the final commit has been applied for the new version then new tags should be created in the local Git repository for each branch/variant of the tool. It is common practice to use tag names by prefixing the version number with the letter v. For the tool tag descriptions also follow a set pattern by explicitly stating if it is a major, minor or patch release.

ArcGIS/MapInfo variant Name: version number prefixed by ‘v’ (e.g. ‘v1.0.8’) Description: Major/Minor/Patch release version number for ArcGIS/MapInfo (e.g. Minor release v1.0.8 for ArcGIS/MapInfo)

Note

To create the above tag example enter the following in a Git shell whilst the master branch is active:

git tag -a v1.0.8 -m ‘Minor release v1.0.8 for ArcGIS/MapInfo’

MapInfo variant Name: version number prefixed by ‘v’ and suffixed by ‘m’ (e.g. ‘v1.0.8m’) Description: Major/Minor/Patch release version number for MapInfo only (e.g. Minor release v1.0.8 for MapInfo only)

Note

To create the above tag example enter the following in a Git shell window whilst the master-mapinfo branch is active:

git tag -a v1.0.8m -m ‘Minor release v1.0.8 for Mapinfo only’

Once the tags have been created in the local repository they should be pushed to the remote GitHub repository.

Note

To push new tags to GitHub enter the following in a Git shell window:

git push --tags

Tip

Existing tags for the tool can be viewed on GitHub under HLUTool Tags.

7.2.2. Release Notes

Each new version/variant of the tool should be accompanied by its own set of release notes. Release notes are written using GitHub Flavored Markdown and should contain the following information as a minimum:

  • Version

  • Release date

  • System requirements

  • Installation Instructions

  • Additions

  • Removals

  • Changes

  • Fixes

Once the new tags for each branch/variant have been pushed to the GitHub repository then release notes can be added. To add release notes go to the list of HLUTool Tags and click Add release notes against the required tag.

Tip

Existing release for the tool can be viewed on GitHub under HLUTool Releases.

7.2.3. Upload Executables

Finally, once each new release has been created on GitHub the associated installer setup.exe executable can be uploaded. This provides an effective way of distributing the tool and ensures that the installer is stored alongside the relevant release notes and source code for each version/variant.

Note

To attach the setup.exe installer to a release, edit the release on GitHub and then ‘drag and drop’ the file on the Attach binaries by dropping them here area.