Re: [DTrace-devel] [PATCH v2 3/4] Sync up the version numbers

Nick Alcock
2025-07-22T10:52:05Z

On 25 Jun 2025, eugene loh verbalised:

> From: Eugene Loh <eugene.loh@oracle.com>
>
> DTrace has many version numbers -- e.g., for the release, packaging,
> and API.
>
> In reality, the variations in numbering have become nearly meaningless:

Tell me about it :(

> - Packaging numbers -- like the Version in the dtrace*spec RPM spec
> file and the VERSION in GNUmakefile -- have basically been tracking
> the DTrace release since 2.0 anyway.
>
> - Stability attributes for idents are haphazard. Generally, they
> are 1.0 (or sometimes other 1.x), and all the BPFs are 2.0. While
> this is generally accurate, it is not exactly robust, and idents
> are sometimes introduced or modified without careful regard to
> the version number. Further, the stability of user D scripts is
> likely to depend more on kernel variations -- e.g., the contents of
> available_filter_functions -- than on D changes.
>
> - Version number updates are susceptible to mistakes, and so there
> have been version mismatches.
>
> Bring the version numbers into sync for 2.0.3. Clean up the descriptions
> in dt_version.h.

So... this means all the ident version numbers change to 2? I doubt it :)
but at least we *have* 2.0.[23] stability-related version numbers now.

Reviewed-by: Nick Alcock <nick.alcock@oracle.com>

modulo the tiny nit below.

> Signed-off-by: Eugene Loh <eugene.loh@oracle.com>
> ---
> GNUmakefile | 5 +-
> dtrace.spec | 1 +
> libdtrace/dt_open.c | 4 ++
> libdtrace/dt_version.h | 54 ++++++++++++--------
> test/unittest/dtrace-util/tst.APIVersion.r | 2 +-
> test/unittest/dtrace-util/tst.APIVersion.r.p | 6 +++
> test/unittest/options/tst.version.r | 2 +-
> test/unittest/options/tst.version.sh | 4 +-
> 8 files changed, 52 insertions(+), 26 deletions(-)
> create mode 100755 test/unittest/dtrace-util/tst.APIVersion.r.p
>
> diff --git a/GNUmakefile b/GNUmakefile
> index d1e18bb1b..00269785b 100644
> --- a/GNUmakefile
> +++ b/GNUmakefile
> @@ -3,7 +3,7 @@
> # Build files in subdirectories are included by this file.
> #
> # Oracle Linux DTrace.
> -# Copyright (c) 2011, 2024, Oracle and/or its affiliates. All rights reserved.
> +# Copyright (c) 2011, 2025, Oracle and/or its affiliates. All rights reserved.
> # Licensed under the Universal Permissive License v 1.0 as shown at
> # http://oss.oracle.com/licenses/upl.
>
> @@ -14,7 +14,8 @@
> SHELL = /bin/bash
>
> PROJECT := dtrace
> -VERSION := 2.0.1
> +# When updating version, see comments in dt_version.h.
> +VERSION := 2.0.3

Oh dear :( this one isn't invisible to users...

> diff --git a/libdtrace/dt_version.h b/libdtrace/dt_version.h
> index 0f47ea70d..5cfcab69a 100644
> --- a/libdtrace/dt_version.h
> +++ b/libdtrace/dt_version.h
> @@ -37,32 +37,28 @@ extern "C" {
> *
> * These #defines are used in identifier tables to fill in the version fields
> * associated with each identifier. The DT_VERS_* macros declare the encoded
> - * integer values of all versions used so far. DT_VERS_STRING must be an ASCII
> - * string that contains the latest version within it along with any suffixes
> - * (e.g. Beta). You must update DT_VERS_STRING when adding a new version,
> - * and then add the new version to the _dtrace_versions[] array declared in
> - * dt_open.c.
> + * integer values of all versions used so far.
> *
> - * Refer to the Solaris Dynamic Tracing Guide Versioning chapter for an
> - * explanation of these DTrace features and their values.
> + * The major number should be incremented when a fundamental change has been
> + * made that would affect all consumers, and would reflect sweeping changes
> + * to DTrace or the D language.
> + *
> + * The minor number should be incremented when a change is introduced that
> + * could break scripts that had previously worked; for example, adding a
> + * new built-in variable could break a script which was already using that
> + * identifier.
> + *
> + * The micro number should be changed when introducing functionality changes
> + * or major bug fixes that do not affect backward compatibility -- this is
> + * merely to make capabilities easily determined from the version number.
> + *
> + * Minor bugs do not require any modification to the version number.

Nice general rules! Now we just have to follow them :)

> + * When the version number is updated, the following must be kept in sync:
> + *
> + * libdtrace/dt_version.h DT_VERS_STRING, an ASCII string that contains
> + * the latest version within it along with any
> + * suffixes (e.g. Beta)
> + *
> + * libdtrace/dt_open.c _dtrace_versions[]
> + *
> + * dtrace.spec Version
> + *
> + * libdtrace/Build libdtrace_VERSION
> + *
> + * GNUmakefile VERSION

I don't think that's quite true -- in particular, libdtrace_VERSION
should only be bumped if it experiences incompatible API or ABI changes,
whether or not DTrace itself has seen e.g. major language changes (which
is why libdtrace_VERSION is not simply $(VERSION) already).

--
NULL && (void)