Copyright (C) 2013 Julian Marchant <onpon4@riseup.net>

Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved.  This file is offered as-is,
without any warranty.

========================================================================


Introduction
------------------------------------------------------------------------

This document describes how version numbering works for SGE, starting on
May 10, 2013.  The purpose of this version numbering system is to
prevent confusion, in particular making it obvious what version of any
given implementation is compatible with a given SGE game.

Note: The specification of the SGE is defined in the SGE Template, so
the version number of the specification is indicated there.


Components
------------------------------------------------------------------------

The version number is divided into three main components: the major
version number, the minor version number, and the bugfix number.  In
addition, files within the SGE's source repository may have an
additional component, the revision number. The components are separated
by a dot (".") in the form: "major.minor.bugfix.revision".  If the
revision number is 0, it should not be specified, and the resulting form
should be: "major.minor.bugfix".

Note: The dot which separates the version number components is not a
decimal point.  Any of the components can increase to any amount.  For
example, the version after "1.3.0.9" is "1.3.0.10", not "1.3.1.0", in
most circumstances.

The components have the following meanings:

* Major version number: This number indicates significant changes to the
  specification which are in most cases likely to break backward
  compatibility.  When this component is increased, all other components
  are reset to 0.

* Minor version number: This number indicates less significant changes
  to the specification, such as feature additions.  In general, minor
  versions are expected to not break backward compatibility; if a game
  works with version 1.2.0 of the SGE, it should also work with version
  1.3.0 in most cases.  When this component is increased, the bugfix
  number and revision number are reset to 0.

* Bugfix version number: This number indicates only fixes to bugs in SGE
  implementations and minor changes to the documentation in the
  specification.  Bugfix releases must never break compatibility except
  in the case where a game's behavior was dependent on a bug in a SGE
  implementation.  When this component is increased, the revision number
  is reset to 0.

* Revision number: This number is only to be used in the source
  repository, specified only in the SGE implementation's __version__
  variable.  This is changed any time the respective SGE implementation
  changes in any way.  A revision number of 0 indicates a version which
  is a stable release, while any other number indicates that the version
  is unstable.  Changes to this version number are allowed to include
  experimentation, untested code, and compatibility breakage.  If this
  component is 0, it should not be specified (see above).

Implementations are expected to have the same major and minor version
numbers as the SGE specification they follow.  The bugfix version number
and revision number may differ from the specification. 

The special major version number "0" indicates the incomplete version.
This is for the time before a complete, stable, and well-tested release
is available.  While the major version number is 0, the minor version
number doubles as the major version number; for example, version 0.3.0
of the specification is permitted to break backward compatibility with
version 0.2.0.  All other version number components remain the same.


Incrementing Version Numbers
------------------------------------------------------------------------

Within the source repository, any time a change is made to a SGE
implementation (the template is also treated as an implementation for
this purpose), the revision number for that implementation (found in
the implementation's __version__ variable in __init__.py) MUST be
incremented.  This includes even minor changes, such as adding,
changing, or removing comments or docstrings, in addition to major
changes.  If a change is reverted, bringing the code back to the way it
was in a previous revision, the revision number is still increased; if
version 1.0.0.25 was undesired and the state is reverted to the way it
was in 1.0.0.24, the version number will be set to 1.0.0.26.

All other version number components must remain static during
development.  They are only to be increased, following the respective
rules of each component, when the code is tested and ready for a
release; at this time, the version number components are adjusted
according to their respective rules and how the source has changed since
the last time this occurred.  The release will be made once all files
which are to be included in the release are ready.

If a blocking bug is detected in an implementation after its version
number has been set for a new release, but before it is released, the
blocking bug may be fixed with the revision number incremented.  In that
case, the implementation's __version__ variable will retain the revision
number, but the release will still be specified without a revision
number.  This situation should be avoided by testing all software
thoroughly before incrementing the version number for a release.  If a
bug is detected during this time, but it is not blocking, the release
will be made anyway.  A blocking bug is defined as one which either has
a potential to cause users harm (e.g. by deleting or corrupting files)
or unintentionally breaks compatibility with previous releases.
