Language support for deprecation

Brainstorming
1

According to a quick search of the zig repo, there are 27 files with /// Deprecated in them, most from the standard library.

Given that zig aims to enable maintainable software, what do you think about language features regarding deprecation?

An obvious non-language-level utility would be a third-party linter looking for Deprecated in doc comments.

What existing features of zig aid the maintainability of libraries and user code through deprecation cycles?

Some existing semi-related maintainability features I have found nice:

  1. User code (and library code when refactoring) sometimes doesn’t need to change very much when types change from pointers to values, since fields of struct pointers can be directly accessed with ., like my_struct_pointer.my_field, which contrasts with C requiring the -> (arrow) operator.
  2. An enum type can be changed to a tagged union typically without changes to user code in switches.
2 Likes
2

Doesn’t need to be a language feature I think? Spitballing, the user code can do

pub const std_options = .{
    .deprecation_warnings = true,
};

and then the library could do

pub fn a_deprecated_function() {
    comptime if (@import("root").std_options.deperecation_warnings) {
        @compileLog("'a_deprecated_function' is deprecated, use 'a_better_function' instead")
    }
}

Would love for std to do this actually, it should ease Zig upgrades quite a bit!

13 Likes
3

of course, status quo zig cannot do this bc std.Options does not have a deprecation_warnings field.

user code can do something like this today though:

const root = @import("root");
pub const aDeprecatedFunction = if (@hasDecl(root, "deprecation_warnings") and root.deprecation_warnings) {
    @compileError("'aDeprecatedFunction() is deprecated, use aBetterName() instead!")
} else aBetterName;

pub fn aBetterName() { ... }

ETA – could also make “deprecation_warnings” an options module in one’s build.zig so that users of a library could opt into them as part of the build process.

4

I think for user code a build option is the way to go. If deprecation_warnings does become a std option, then it might make sense to use an enum instead of a bool:

const DeprecationWarning = enum {
    ignore,
    compile_log,
    use_std_option,
};

Then default to .use_std_option if the user doesn’t pass in anything.

Although, I’m not sure when you would want to see only a subset of the deprecations.