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

[Nick Alcock <nick.alcock@oracle.com>]

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)