mirror of https://github.com/svaarala/duktape.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
142 lines
6.8 KiB
142 lines
6.8 KiB
<h1 id="versioning">Versioning</h1>
|
|
|
|
<h2 id="semantic-versioning">Semantic versioning</h2>
|
|
|
|
<p>Duktape follows <a href="http://semver.org/">Semantic Versioning</a>:</p>
|
|
<ul>
|
|
<li>Major version changes when API incompatible changes are made.</li>
|
|
<li>Minor version changes when backwards-compatible functional changes are made.</li>
|
|
<li>Patch version changes when backwards-compatible bug fixes are made.</li>
|
|
</ul>
|
|
|
|
<p>The "public API" to which these rules apply include:</p>
|
|
<ul>
|
|
<li>The Duktape API calls documented on duktape.org; except those tagged
|
|
<code>experimental</code>.</li>
|
|
<li>The global environment visible to Ecmascript code, including the <code>Duktape</code>
|
|
object and other Ecmascript extensions, as documented on duktape.org;
|
|
except changes needed to align with latest Ecmascript specifications.</li>
|
|
</ul>
|
|
|
|
<p>The following are not part of the "public API" versioning guarantees:</p>
|
|
<ul>
|
|
<li>Duktape API calls tagged <code>experimental</code>.</li>
|
|
<li>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.</li>
|
|
<li>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).</li>
|
|
<li>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.</li>
|
|
<li>Specific behavior which is explicitly noted to potentially change even in
|
|
minor versions, for example:
|
|
<ul>
|
|
<li>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.</li>
|
|
</ul>
|
|
</li>
|
|
<li>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.</li>
|
|
<li>Extras distributed with Duktape (<code>extras/</code> directory).</li>
|
|
</ul>
|
|
|
|
<p>When a patch version is released, the following things are guaranteed:</p>
|
|
<ul>
|
|
<li>API binary compatibility is maintained: constant values don't change, function
|
|
typing doesn't change, API call function/macro status doesn't change.</li>
|
|
<li>Bytecode dump/load format doesn't change so that you can load bytecode
|
|
dumped from an older version which only differs in patch version.</li>
|
|
<li>Ecmascript semantics fixes are not included unless necessary to fix
|
|
a bug.</li>
|
|
<li>Config options won't change in an incompatible manner.</li>
|
|
</ul>
|
|
|
|
<h2 id="experimental-features">Experimental features</h2>
|
|
|
|
<p>Some new features and API calls are marked <b>experimental</b> which means
|
|
that they may change in an incompatible way even in a minor release.<p>
|
|
|
|
<p>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.</p>
|
|
|
|
<h2 id="version-naming">Version naming</h2>
|
|
|
|
<p>Releases use the form <i>(major).(minor).(patch)</i>, e.g. <b>1.0.3</b>.</p>
|
|
|
|
<p>Development pre-releases use the form <i>(major).(minor).(patch)-alpha.(number)</i>,
|
|
e.g. <b>1.3.0-alpha.2</b>. The form <i>0.(minor).0</i> was used for development
|
|
pre-releases before the 1.0 release.</p>
|
|
|
|
<h2>DUK_VERSION and Duktape.version</h2>
|
|
|
|
<p><code>DUK_VERSION</code> and <code>Duktape.version</code> provide version
|
|
identification using a single number computed as:
|
|
<code>(major * 10000 + minor * 100 + patch)</code>,
|
|
then subtracting one for development pre-releases.</p>
|
|
|
|
<p>Note the limitations for development pre-releases:</p>
|
|
<ul>
|
|
<li>Development pre-releases for the same release are not distinguished from
|
|
one another: for example, both 1.3.0-alpha.1 and 1.3.0-alpha.2 are
|
|
identified as 10299.</li>
|
|
<li>Development pre-releases for patch releases are not distinguished from the
|
|
previous patch release: for example, 1.3.3-alpha.6 and 1.3.2 are both
|
|
identified as 10302.</li>
|
|
</ul>
|
|
|
|
<p>Development pre-releases shouldn't be used in production, but the current
|
|
<code>DUK_VERSION</code> and <code>Duktape.version</code> number provides
|
|
a useful approximation for version comparison: an alpha release will compare
|
|
smaller than the actual release, but higher (or equal) than a previous release.</p>
|
|
|
|
<h2 id="versioning-examples">Examples</h2>
|
|
|
|
<p>The table below provides some examples, in ascending version order:</p>
|
|
<table>
|
|
<tr>
|
|
<th>Version</th>
|
|
<th>Pre-release?</th>
|
|
<th>DUK_VERSION &<br />Duktape.version</th>
|
|
<th>Notes</th>
|
|
</tr>
|
|
<tr><td>0.12.0</td><td>yes</td><td>1200</td><td>Pre-release before 1.0 release.</td></tr>
|
|
<tr><td>1.0.0</td><td>no</td><td>10000</td><td></td></tr>
|
|
<tr><td>1.3.0-alpha.1</td><td>yes</td><td>10299</td><td>Identified like 1.2.99, first 1.3.0 development pre-release.</td></tr>
|
|
<tr><td>1.3.0-alpha.2</td><td>yes</td><td>10299</td><td>Identified like 1.2.99, no difference to 1.3.0-alpha.1.</td></tr>
|
|
<tr><td>1.3.0</td><td>no</td><td>10300</td><td></td></tr>
|
|
<tr><td>1.3.2</td><td>no</td><td>10302</td><td></td></tr>
|
|
<tr><td>1.3.3-alpha.6</td><td>yes</td><td>10302</td><td>Identified like 1.3.2, no difference to 1.3.2 release.</td></tr>
|
|
<tr><td>1.3.3</td><td>no</td><td>10303</td><td></td></tr>
|
|
<tr><td>2.0.0-alpha.3</td><td>yes</td><td>19999</td><td>Identified like 1.99.99.</td></tr>
|
|
<tr><td>2.0.0</td><td>no</td><td>20000</td><td></td></tr>
|
|
</table>
|
|
|
|
<h2 id="version-maintenance">Maintenance of stable versions</h2>
|
|
|
|
<p>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.</p>
|
|
|
|
<h2>Incompatible changes</h2>
|
|
|
|
<p>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:</p>
|
|
<ul>
|
|
<li>When API call semantics are changed, the old API call is removed (causing
|
|
a build failure if used) and a new one is added.</li>
|
|
<li>When support for an old feature option is removed, an attempt to use it
|
|
will cause a build failure.</li>
|
|
</ul>
|
|
|
|
<p>This is not a hard rule, but the default guideline.</p>
|
|
|