Software Version Numbers

This page describes the software version number scheme that I use for my software projects. It is designed to help users of my software chose a version that has

  • an interface they expect,
  • the features they require, and
  • the bug fixes they require.

I do not claim this is the only way to use version numbers. This is one way to use version numbers that solves problems for me and the users of my software.

I do not claim this scheme is original. It is the result of reading about other version reporting schemes and discussions with other software developers over the years. I no longer recall sources or influences.

Use of Software Version Numbers

I use these software version numbers for both large projects, to describe an integrated software system, and for smaller projects for developing pieces to be integrated into large projects.

Version Numbers

This scheme uses a three place version number, I.F.B, where,

  • I is the Interface version.
  • F is the Feature version.
  • B is the Bug fix version.

For example:

  • version 2.3.5 is read as:
    • interface version 2,
    • feature version 3, and
    • bug fix version 5.

Each place is incremented or reset to zero according to formal rules.

Interface Version

The interface version is a count of the number of times the public interface has been cleaned up. The interface version starts at 0 (zero) and is incremented every time a developer cleans up the interface.

Between interface cleanups, it is acceptable to add to public interface, or to deprecate a part of a public interface. It is also acceptable to add new features and fix bugs.

It is not acceptable to remove or rename any part of a public interface, or to remove any features, without an interface cleanup.

Feature Version

The feature version is a count of the number of features completed since the last interface cleanup. The feature version starts at 0 (zero) and is incremented every time a developer completes a new feature. The feature version is reset to 0 when the interface is cleaned up.

Implementing new features will often require adding to an interface.

Between completing new features, it is acceptable to fix bugs. Under this scheme, once a decision has been made to add a feature, its absence may be viewed as one or more bugs. Progress towards completing a feature may be viewed as fixing bugs (implementing pieces of a missing feature).

Bug fix Version

The bug fix version is a count of the number of bugs fixed since the last feature was completed. The bug fix version starts at 0 (zero) and is incremented every time a developer fixes a bug. The bug fix version is reset to 0 when a feature is completed.

Definitions - in work

Public Interfaces

Public interfaces to a piece of software are all of the interfaces the developer of that code has documented as usable by users of their software. This includes the public code interfaces and public human interfaces.

This excludes all implementation details not documented as public interfaces.

Public Code Interfaces

Public Code interfaces include all public classes, interfaces, libraries, modules, packages, etc., that the developer of a piece of software documents as public. This also includes all public exceptions, functions, methods, messages, objects, procedures, variables, etc. contained in those interfaces. This also includes database scheme and table data if data in these databases is shared between pieces of software.

Some languages include language features to identify public and private items. Other languages have established coding conventions to identify public and private items. Some languages have neither. In this case, document as necessary.

Public Human Interfaces

Public Human interfaces include all public command names, command line options, GUI layouts, and menu options and layout.

Some software may include administration, or development or debugging human interfaces. These should be treated as public human interfaces, but should be documented separately because they support different sets of users. Some software may include different human interfaces for supporting different user roles. These should also be documented separately because they support different sets of users.

-- ScottRankin - 2013-09-11
Topic revision: r9 - 2013-11-26, ScottRankin
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding NRAO Public Wiki? Send feedback