Version Control And File Naming Advice

Introduction

When you move on to creating Plugins for yourself or for the Plugin Store it really helps to be able to manage the files and the file levels. These notes are intended to help Plugin authors make use of available tools as well as produce consistent Plugins

Using a Main Function

Although not required, it can be a good idea to use a main function for any more complex Plugins that use extra functions, as it allows you to keep the main code at the top of the source code.

A simple example would be

function main()
  print(hello())
end

function hello()
  return 'hello'
end
---------------------------- call main function
main()

The Script Header

Edit >> Insert Script Header

When starting a Plugin it's a very good idea to add a Plugin Header which can easily be done from the Edit » Insert Script Header option.

This will insert the following to the top of your file.

--[[
@Title: 
@Author: 
@Version: 
@LastUpdated: 
@Description: 
]]

The @Title: should exactly match the Plugin name, and use only alpha-numeric characters.

Remember to keep the @LastUpdated: date in line with your latest changes.

It's a good idea to start with a @Version: number of 0.1.0 for the prototypes and then move up to 1.0.0 when you are ready to release the Plugin to the Plugin Store as explained in more detail below.

The @Description: field can be written over multiple lines; leave a blank line to mark paragraphs.

It is recommended that a log of changes is recorded in the header after the Description, using a format such as:

@Description: This plugin provides various date conversions.
@ChangeLog: 
@V0.1.0:      First prototype attachment to the FHUG Forum.
@V0.1.1:      Fixed double date conversion problem.
@V1.0.0:      First published release into the Plugin Store.
]]

Plugin Names and Dates

If you're developing plugins that will be released via the Plugin Store, it's important that you name things consistently. All of the following should be the same, including capitalisation:

  • The @Title: section in your plugin header, e.g. My Wonderful Plugin
  • The Plugin Title in the Plugin Store, e.g. My Wonderful Plugin
  • The File name in the Plugin Store (which will be the file name when downloaded), e.g. My Wonderful Plugin.fh_lua

This will avoid confusing your users, and will enable the Check Installed Plugins Against the Store plugin to include your plugin accurately.

Ensure that the @LastUpdated: date agrees with the date you submit your Plugin to the Plugin Store.

Version Numbers

Each distinct version of your plugin should have a different version number (as recorded in the @Version: section in your plugin header. It is recommended that you adopt Semantic Versioning, which uses a three part numbering system (and is used by Family Historian itself):

  • MAJOR version (incremented when significant new features are released, or changes are released that are not backwards compatible with previous versions – e.g. file/data formats in a new version will not be readable in previous versions)
  • MINOR version (incremented when minor new features are released and there are no backwards-compatibility issues)
  • PATCH version (incremented when bug fixes are released without new features)

Each element of the version number is an integer starting from 0, without leading zeroes.

MAJOR version 0 is reserved for development/testing before the first release of your plugin. Whenever the MAJOR version is incremented, MINOR AND PATCH levels are initially set to zero.

The authors of very simple plugins may decide not to use the PATCH version component, although it can be very useful for tracking bug-fix releases.

Version Control

In the commercial programming world, version control systems are very important as they allow a fairly easy way of tracking changes over time.

There are many different ones and some need a dedicated server. However, there are several systems for Windows which are suitable for home Plugin writers.

A fairly easy to use Windows control system is Git for Windows, which once installed allows the easy creation of a repository (where all the changed code lives) inside your Plugins folder and allows files to be managed easily using right click on the files in the folder or using Git Gui. There is a nice (if somewhat out of date) guide to getting started with git at NathanJ:An Illustrated Guide to Git on Windows; for home use you can ignore the Putty section.

The latest version can be downloaded from Git for Windows.

A version control system will help you keep control of your version numbers.