Versioning
Semantic versioning
Duktape follows Semantic Versioning for
official releases:
- Major version changes when API incompatible changes are made.
- Minor version changes when backwards-compatible functional changes are made.
- Patch version changes when backwards-compatible bug fixes are made.
The "public API" to which these rules apply include:
- The Duktape API calls documented on duktape.org; except those tagged
experimental
.
- The global environment visible to ECMAScript code, including the
Duktape
object and other ECMAScript extensions, as documented on duktape.org;
except changes needed to align with latest ECMAScript specifications.
The following are not part of the "public API" versioning guarantees:
- Duktape API calls tagged
experimental
, and any other features
documented as experimental.
- Internal calls made by API macros. While API calls implemented as macros
are part of the public API, any internal calls the macros make are not,
even if their symbol visibility is public.
- Changing an API call from a function call to a macro (or vice versa).
These are considered compatible changes (but are not done in patch releases).
- Aligning with latest ECMAScript specifications. Duktape tracks the latest
ECMAScript specification (currently ES2016). Backwards incompatible changes
required to align with the latest specifications may be done in minor
versions too (but not in patch versions unless necessary to fix a bug).
Typically such changes are relatively minor, for example argument coercion
or property inheritance changes.
- Specific behavior which is explicitly noted to potentially change even in
minor versions, for example:
- Behavior of buffer objects when their backing buffer is smaller than
the apparent size of the buffer object. Memory safe behavior is
guaranteed, but otherwise behavior may vary between versions.
- Duktape config options. Incompatible config option changes are not made in
patch releases, but can be made in minor releases. The goal is to cause a
compile error (if possible) when a no-longer-supported feature option is
used so that any incorrect assumptions can be fixed.
- Extras distributed with Duktape (
extras/
directory).
When a patch version is released, the following things are guaranteed:
- API binary compatibility is maintained: constant values don't change, function
typing doesn't change, API call function/macro status doesn't change.
- Bytecode dump/load format doesn't change so that you can load bytecode
dumped from an older version which only differs in patch version.
- ECMAScript semantics fixes are not included unless necessary to fix
a bug.
- Config options won't change in an incompatible manner.
Development builds made from Duktape repo are not official releases and
don't follow strict semantic versioning.
Experimental features
Some new features and API calls are marked experimental which means
that they may change in an incompatible way even in a minor release.
Features may be marked experimental e.g. because they are useful but
incomplete, or because the best design is not obvious and it's useful to
gather some feedback before committing to the design. Typically a feature
is experimental for one minor release and then, after the necessary changes,
becomes a fully supported feature.
Version naming
Releases use the form (major).(minor).(patch), e.g. 1.0.3.
DUK_VERSION and Duktape.version
DUK_VERSION
and Duktape.version
provide version
identification using a single number computed as:
(major * 10000 + minor * 100 + patch)
,
then subtracting one for development builds (not official releases) made from
Duktape repo.
Note the limitations for development builds:
- Development builds for the same upcoming release are not distinguished from
one another: for example, all builds from master prior to 1.3.0 release
are identified as 10299.
- Development builds for patch releases are not distinguished from the
previous patch release: for example, a development build after 1.3.2 but
before 1.3.3 is identified as 10302.
Development builds shouldn't be used in production, but the current
DUK_VERSION
and Duktape.version
number provides
a useful approximation for version comparison: a development build will
compare smaller than the actual release, but higher (or equal) than a
previous release.
Examples
The table below provides some examples, in ascending version order:
Version |
DUK_VERSION & Duktape.version |
Notes |
0.12.0 | 1200 | |
1.0.0 | 10000 | |
1.2.99 | 10299 | Development build before 1.3 release. |
1.3.0 | 10300 | |
1.3.2 | 10302 | |
2.0.0 | 20000 | |
Maintenance of stable versions
There's no long term maintenance policy yet: stable versions will get bug
fixes (patch releases) at least until the next stable version has been
released, and there has been some time to migrate to it.
Incompatible changes
The general goal for incompatible changes is that an application relying
on old, unsupported features will fail to build. It is preferable to have the
build fail rather than to be silently broken. This means for example that:
- When API call semantics are changed, the old API call is removed (causing
a build failure if used) and a new one is added.
- When support for an old feature option is removed, an attempt to use it
will cause a build failure.
This is not a hard rule, and it cannot be achieved in all cases.