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.
3 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!

15 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.

5

There is now a proposal for a @deprecated() builtin.

2 Likes
6

As long as depreciation marking includes zig fmt automation when feasible!

7

I wonder if instead of another builtin just to mark something deprecated it wouldn’t be better to add a builtin to attach an attribute, and the “deprecated” can just be an attribute value then.

8

I wonder if instead of another builtin just to mark something deprecated it wouldn’t be better to add a builtin to attach an attribute, and the “deprecated” can just be an attribute value then.

That sounds similar to various pragma/attribute issues, all of which I believe are rejected or closed.

Here’s one such issue, which has deprecation as one of the examples: Proposal: Pragmas · Issue #5239 · ziglang/zig · GitHub

9

@deprecated() has been merged, looking forward to trying it out! (… though not saying I look forward to writing code that I later have to remove, slowly and painfully, from my non-existent users…)

5 Likes