What’s in a number?

Introduction

You see them everywhere with software, version numbers. You get reminded of updates with words along the lines of ‘update to version X’. When you have an issue you always (at least should) get asked the question ‘What version are you running?’. But why? Why are they so important?

Disclaimers

Moodle™ is a registered trademark of ‘Martin Dougiamas’ – moodle.com/trademarks.

Other names / logos can be trademarks of their respective owners. Please review their website for details.

I am independent from the organisation listed above and am in no way writing for or endorsed by them.

What a version number is

A version number is a combination of symbols (not just a number but can be) that is applied to a given element of software at a given moment in time. That ‘element’ can be one thing or a collection of things, so one of the files used or a collection of files that represent something, like a Moodle theme or an app on your phone.

That ‘moment in time’ is the key thing here, it is saying that this ‘element’ has this ‘state’ at this ‘time’.

Why it is so important

Version numbers are like seeing batch numbers on food products so that a given collection of a given product can be traced to a given moment in time when they were made and critically the ‘what, who and how’ in case there is an issue. So with software it is the same thing. The ‘version number’ is applied like a stamp to state that the software has this ‘state’ at this ‘time’ and if there are any issues then knowing the state is critically important in user standing how the software works at that given moment.

So knowing the version number allows the developer of the software to be in a position to understand and critically ‘replicate’ your issue in order to ‘debug’ (find out what is wrong) the problem and then hopefully come up with a solution. This is because they are able to replicate the same software environment as you have and with more information like screen shots and the steps you took, investigate what is going on.

A bit about debugging

Debugging is like being a detective, you examine what has happened in a state as close as possible to when the incident happened. It is a skill based upon knowledge and understanding. From a software engineers perspective, the version number is the key that unlocks the door to the room that they investigate to find out what happened.

A long time ago I was told a joke (I can’t remember by whom) that goes along the lines of:

A car starts at the top of a hill, suddenly it starts to move down the hill and crashes at the bottom. The occupants are uninjured.
At the bottom are a chemist, engineer, manager and software engineer.

The chemist says “The brake fluid must be bad”.
The engineer says “Ah, it must be that the brake pads are worn out”.
The manager says “Who is responsible for this?”
The software engineer says “Lets take it back up to the top and see if it happens again”.

Strange though it may seem, replicating a software fault situation and observing the sequence of events that gave rise to it helps to understand why it happened in the first place. Just like you see crash tests with cars where you know what’s going to happen but you want to understand all of the elements of the situation in slow motion. When debugging, you do the same thing, you establish the same set of circumstances then slowly step through the sequence of events that leads up to the final fault. This is why things like screen shots and answers to questions like ‘what did you do’ are so important.

Not the whole story

However, a version number is not the whole story. It is only a part of the process of ‘Software configuration management’ or ‘SCM’ for short (en.wikipedia.org/wiki/Software_configuration_management – stated here as ‘revision control’). SCM is a process that helps to know how to manage all of the elements of a piece of software over time. And there is already tools out there to help you manage this, such as ‘Gogs’ as mentioned in ‘Icing on the Pi’.

Once I know the version number then I start to investigate the issue using my knowledge of the state of the software at the time, along with other reported elements like a ‘stack trace’, which I’ll describe in a moment, and screen shots. If the version number represents a state that is in the past then looking at the changes since then gives an indication if the problem has already been solved.

A ‘stack trace’ is like a ‘path through the software to the problem’. The ‘path’ has numbers that represent the line numbers in the code files. The code at each line can change over time and will only be truly consistent for a given version. A stack trace is really helpful in pin pointing a problem and is worth stating if you see one on the screen or in the error logs.

Screen shots, especially when annotated to point out the issue, give visual understanding of the issue because the developer will understand how something is created for the user interface output and thus know (or be able to find) the code that generated it. Therefore if it is wrong, be in a position to potentially fix it.

Conclusion

Version numbers are not the whole story in software bug fixing but they go a long way in reducing the size of the haystack to search. So by providing them, you help yourself by reducing the time the developer takes to solve your problem.

Bug fixing is also a ‘challenge’, its a mountain that is just waiting to be climbed.

Gareth Barnard

Gareth Barnard

Developer at HRDNZ
Gareth is a developer of numerous Moodle Themes including Essential (the most popular Moodle Theme ever), Shoelace, and other modules such as course formats.
Gareth Barnard

Latest posts by Gareth Barnard (see all)

blank

Gareth Barnard

Gareth is a developer of numerous Moodle Themes including Essential (the most popular Moodle Theme ever), Shoelace, and other modules such as course formats.

2 thoughts on “What’s in a number?

  • 17th January 2019 at 8:17 am
    Permalink

    Create post Gareth!
    I can see how this is absolutely critical in bug fixing situations.
    But I have to say, that even in ‘general support’ situations it can be really vital and extremely helpful information.
    I’ve lost count of the number of times someone asking for Moodle support for example doesn’t give us the version of Moodle they use – and that can have a big impact as features may or may not exist, be in a different location, or work differently.
    And YES! Screenshots! Often an support request doesn’t use the right terminology.

    Reply

Add a reply or comment...

%d bloggers like this: