@deprecated() builtin

[kristoff-it]

Motivation

It's already an established pattern in the Zig ecosystem to deprecate declarations first via a doc comment, and after a while by turning the old decl into a @compileError once the deprecation "grace period" is over, to then finally delete the decl altogether after some more time.

Currently a user that is interested in discovering early which APIs are being deprecated must grep the codebase for the word, find the decl the comment refers to, and figure out if and where its being used (directly or not) in the codebase.

Conversely, a library author that wants to maintain backwards compatibility (i.e. avoid a major version bump for a v1 package) will not want to set deprecated decls to @compileError as that would be a compatibility breakage, never giving users an opportunity to leverage compile errors to migrate their API usage.

It is possible today to implement a better solution entirely in userland:

// build.zig
fn build(b: *std.Build) void {
    const opts = b.addOptions();

    opts.addOption("deprecated", b.option(
        bool,
        "deprecated",
        "turn deprecated decls into compile errors",
    ) orelse false);
}

// root.zig
const options = @import("options");

fn oldFoo() void {
    if (options.deprecated) {
        @compileError("deprecated, use newFoo()");
    }
}

/// Deprecated: use `GenericWriter`
const Writer = if (options.deprecated) @compileError("deprecated, use `GenericWriter`") else GenericWriter;

Running zig build -Ddeprecated will turn deprecated decls in compile errors giving both a nice compiler-driven upgrade experience to users, while letting library authors maintain backwards compatibility.

This pattern seems so useful that might be worth enshrining it as a standardized practice.

Proposal

Introduce a @deprecated() builtin and a new -fdeprecated compiler flag to be used like so (this is a contrived example to showcase the workflow):

// main.zig
const std = @import("std");

const num = @deprecated(10);

pub fn main() void {
    std.debug.print("num: {}\n", .{num});
}

$ zig run main.zig
num: 10

$ zig run main.zig -fdeprecated

main.zig:3:13: error: found deprecated code
const num = @deprecated(10);
            ^~~~~~~~~~~~~~~
referenced by:
    main: main.zig:6:34
    posixCallMainAndExit: zig/lib/std/start.zig:647:22
    4 reference(s) hidden; use '-freference-trace=6' to see all references

A less contrived example would be the current deprecation of std.time.sleep in the Zig standard library:

/// Deprecated: moved to std.Thread.sleep
pub const sleep = std.Thread.sleep;

pub const sleep = @deprecated(std.Thread.sleep);

A second example: using @deprecated in a function body:

const Strategy = enum { greedy, expensive, fast };

fn compute(comptime strat: Strategy, comptime foo: bool, bar: usize) void {
    switch(strat) {
        .greedy => {
            // This strategy turned out to be bad when foo is false,
            // use the fast strategy instead.
            if (!foo) @deprecated();
            runGreedy(foo, bar);
        },
        .expensive => runExpensive(foo, bar),
        .fast => runFast(foo, bar),
    }
}

Lastly, since @deprecated conveys intent more precisely, tooling like LSPs and linters could offer diagnostics about deprecation automatically to the user in a more streamlined fashion than with the full userland solution.

A branch with @deprecated implemented can be found here: https://github.com/kristoff-it/zig/tree/deprecated-proposal (diff)

[RetroDev256]

Can't wait for when we deprecate the @deprecated builtin ;)
Sounds like a smooth idea though, goes along with zig fmt fixups

[haze]

Is there merit in requiring the author to provide a string or alternative symbol to steer users in the right direction? Is a comment on the same line enough?

[nektro]

i think the rejection of #3320 and the demonstration of the userspace solution shows that this would fit much better as a standard library module or 3rd party package, than as a builtin

[kj4tmp]

Pros:

• supports maintainability goal of zig, deprecation is a key aspect of maintaining long-running projects and this would make it a "first-class" feature. Linting on "deprecated" in a doc comment is false-positive prone and this builtin will assist tooling.
• supports only one obvious way to do things zen, this would be the only obvious way to mark deprecation
• supports a use-case where a user wants to get a head start on preparing for deprecation / breaking API changes. Could argue this is not a compelling use case. If the code compiles and works, changes should not be made until upgrading the dependency is required for some other reason (security, features, etc). Could also argue that this is tech debt and we should support if possible its reduction quickly, early, and efficiently.
• could prevent a user from wasting time implementing a solution that uses a deprecated API, only to have to change it later

Cons:

• conversely also undermines only one obvious way to do things zen, user must decide if they will use -Ddeprecated or not.
• (fundamentally new?) change to compile flags that would allow code to sometimes compile and sometime not (I'm thinking of warnings for C compilers here) (see rejection of Hacking-friendly "--sloppy" mode for Zig. #3320)
• adds an additional failure mode that user must "hold in their head" when debugging issues with (yet to be created) maximum version selection: Version selection system for the official package manager #8284
• -fno-deprecated is viral. As soon as my dependency starts having them and spamming my compiler output, I have to start ignoring them (or fix my dependency), but I suspect most will ignore them unless forced (see C compiler warnings!).

My conclusion:

Due to the virality of -fno-deprecated and the fundamental change to compile flags I think this should not be added. Maybe we add it but don't ever generate errors for it just so tooling/linters can reliably detect it.

[fluffinity]

i think the rejection of #3320 and the demonstration of the userspace solution shows that this would fit much better as a standard library module or 3rd party package, than as a builtin

So maybe implement this as a std function std.deprecrated? Getting this into std would at least mean the functionality does not need to be replicated across multiple projects.

Is there merit in requiring the author to provide a string or alternative symbol to steer users in the right direction? Is a comment on the same line enough?

It should definitely take a comptime string as an argument. This would make the message more explicit than a comment, which can easily get overlooked. Something like this should work:

pub fn depecrated(comptime message: []const u8, value: anytype) @TypeOf(value)

Due to the virality of -fno-deprecated and the fundamental change to compile flags I think this should not be added. Maybe we add it but don't ever generate errors for it just so tooling/linters can reliably detect it.

Maybe make this behavior configurable in the build.zig then? At least application authors should have the option to warn/error on deprecations. The problems you mention seems to primarily concern libraries. That being said, deprecation notices should be visible without external tooling, i.e the Zig compiler and ZLS should suffice to see it. Lets not become C/C++ in this regard.

[castholm]

As proposed, @deprecated seems like it would run into all the same problems that make optional warnings or --sloppy bad ideas in that all Zig code will get categorized as either "code that treats deprecations as errors" or "code that doesn't" and make it difficult for the former category to interact with the latter. Even the suggested user space implementation will have problems if you consider the case where I directly depend on and want package A with -Ddeprecated=true but I also depend on package B which wants package A with -Ddeprecated=false, resulting in package A not being deduplicated (which may or may not be a problem depending on how tightly integrated the packages are).

Speaking purely in the context of std, I believe the main problem people have with the current deprecation strategy is the lack of discoverability of deprecation notices, not the lack of compile errors. There's no good way as a user to get notified of a /// Deprecated doc comment unless you're diligently reading the documentation for all std APIs you interact with every time you update to a new Zig build. This leads to many projects only learning about deprecations when it's already too late and the affected APIs have already been removed or replaced, which is frustrating.

As much as I hate the term "code smell" it's also important to realize that using a deprecated API is a code smell, not a bug; a questionable pattern in your code that you should probably address, but not something that should necessarily break your build until you fix it. Any solution to the problem with status quo deprecations should focus on addressing the question "how can we let users know that they are using a deprecated API?" before it tries to go for "how do we prevent users from using a deprecated API?".

If there was some static analyzer or linter, either provided by a third-party or built into the zig CLI, that you could run (possibly as a separate step as part of your build process) to detect references from your own code to symbols documented with /// Deprecated and log them, it would solve the discoverability problem. Users could then run this tool/command after updating Zig and/or a dependency, get a list of deprecations and choose how, when and whether to address them.

[andrewrk]

Accepted, with adjustments:

• flags are -fallow-deprecated and -fno-allow-deprecated.
• Modules created by the root package default to -fno-allow-deprecated.
• Modules created by dependency packages default to -fallow-deprecated.
• Build system does not expose an option to set this flag.
• zig build exposes -fallow-deprecated and -fno-allow-deprecated, applying it globally to entire dependency tree.

In other words, maintainers by default cannot make the mistake of calling into deprecated API, however, the dependency tree by default will not fail in "other people's code" due to deprecations.

To those who think this is the same thing as "sloppy mode": whereas sloppy mode would create two factions in the ecosystem who each prefer a different dialect of Zig, nobody wants to be using deprecated code. Programmers will naturally steer clear of any packages that require -fdeprecated in order to build, because it's an obvious clue that the package is of poor quality.

[xdBronch]

to clarify, you're saying the default should be that @deprecated() is an error? your wording (and zig philosophy :p) makes me assume yes but the way @kristoff-it wrote the proposal and implemented it is that -fdeprecated == an error is raised which seems to be the opposite of what you've said

[kristoff-it]

Yes Andrew is changing the default behavior.

[kj4tmp]

One pain point with deprecation for library authors is remembering when to turn a value into a compile error. Release schedules can be far apart, with deprecation being applied to many APIs over the course of months.

Should an additional parameter until be added? Making the signature:

fn deprecated(value: anytype, comptime until: []const u8) @TypeOf(value) {}

For example:

pub const sleep = @deprecated(std.Thread.sleep, "0.16.0");

Library authors would put the semantic version of when the value should be removed. And then when the build system attempts a build of the library with semantic version greater than or equal to "0.16.0" it would result in a compile error for the author.

Edit: No, this is already possible in user space with @compileError and branching on information from builtin

[castholm]

The purpose of deprecation in Zig is therefore to help transition code authors to a new API. Due to version locking, errors due to deprecations will only occur when a maintainer upgrades a dependency to a new version.

How well will this play with #8284? Under MVS, if I directly depend on Package A version 1.4, but I also depend on Package B which in turn depends on Package A version 1.2, the build system will pick version 1.4 of Package A. If Package A has marked APIs with @deprecated between 1.2 and 1.4, and Package B uses those APIs, I am now forced to build with -fdeprecated, through no fault of my own. Is that correct?

(Semver specifies that "minor version [...] MUST be incremented if any public API functionality is marked as deprecated". Deprecations are not considered backward-incompatible and don't require a major version bump.)

Programmers will naturally steer clear of any packages that require -fdeprecated in order to build, because it's an obvious clue that the package is of poor quality.

For third-party libraries, this may be true, but for std and for as long as Zig remains pre-1.0, it will make it painful to depend on packages that target a "floating" Zig master version. Even if a package uses APIs that still exist and work, it will need to be updated much more frequently if it wants to avoid burdening consumers with requiring -fdeprecated, and if it wants to simultaneously target multiple Zig versions, it will need to litter the code with even more feature detection or explicit compiler version checks before using APIs that differ between versions.

At that point, the value of deprecation notices in std APIs is greatly diminished and you might as well stop doing them and instead always immediately break APIs by turning them into compile errors the moment they are removed, because both @deprecated and @compileError will put the same pressure on authors who want their packages to be considered "not poor".

[mlugg]

Since the meaning of -fdeprecated isn't clear (Andrew flipped it and I could see either way; either "this lets you use deprecated code" or "this 'enables' @deprecated (so that it triggers errors)"), could I instead propose -fallow-deprecated and -fno-allow-deprecated?

[andrewrk]

How well will this play with #8284?

Ah, now that's a delightfully productive question.

Note that this case still fits the pattern that the project built fine with -fno-allow-deprecated, and then the maintainer changes the dependency graph by adding a new package, and now there is a problem of deprecated API being used. This is equivalent to the existing problem of code being upgraded to a new version of a package and experiencing different behavior.

So it is still satisfying this use case:

The purpose of deprecation in Zig is therefore to help transition code authors to a new API. Due to version locking, errors due to deprecations will only occur when a maintainer upgrades a dependency to a new version. -fallow-deprecated is then a tool to help during the upgrade process, but the upgrade process will only be complete when the project compiles without the flag.

However, I'm going to backtrack a little bit, because it is still a bit of a problem in the sense that the purpose of deprecation, as pointed out via the semver quote, is to have a grace period in which the code continues to compile by default. The thing that makes me willing to backtrack here is considering the fact that the deprecated API can simply be removed when it is time for it to be a compile error, and the purpose of tooling-aware deprecation, then, is specifically for avoiding compilation errors while providing an upgrade path.

Anyway, here's the adjusted plan:

• Modules created by the root package default to -fno-allow-deprecated.
• Modules created by dependency packages default to -fallow-deprecated.

[onthebusiness]

In my mind, it would be better to have a type of compile error, like the logging levels we have in loggers.

[scheibo]

In my mind, it would be better to have a type of compile error, like the logging levels we have in loggers.

Ah yes, lets call it a "warning" 🙃

To those who think this is the same thing as "sloppy mode": whereas sloppy mode would create two factions in the ecosystem who each prefer a different dialect of Zig, nobody wants to be using deprecated code.

To me this feels just like a distinction without a difference - why would I want to be using "sloppy" code either? Weakening Zig's stance on warnings specifically just for @deprecated feels silly to me.

[kj4tmp]

What happens when a library uses its own deprecated API's?

For example, the standard library deprecates std.time.sleep but some area in std.io still uses it? Compile error?

a library author that wants to maintain backwards compatibility

In this scenario, a library author may have a significant number of tests that call deprecated code. If the library author wants to keep these tests, they will need a way to run them without a compile error.

[fluffinity]

For example, the standard library deprecates std.time.sleep but some area in std.io still uses it? Compile error?

The current implementation in kristoff's PR would make this a compile error, unless compiled with fallow-deprecated. I think this behavior is desirable as it is more consistent.

In this scenario, a library author may have a significant number of tests that call deprecated code. If the library author wants to keep these tests, they will need a way to run them without a compile error.

You can compile and run them with zig build -fallow-deprecated test until you are able to update your tests.

[SeriousBusiness101]

can't wait for when we deprecate the @deprecated builtin

"Patch Awareness" is a "Spotty Game"; the concept of a tool acknowledging, from within, that it is versioned and patched.

This, on its own, can only make sense in monolithic sensibilities.
A convention cannot be sound by edict, so I would at least hope to have some feedback on how this should or shouldn't be used in places where one man's builtin is at odds with another man's patch system.

[kj4tmp]

For example, the standard library deprecates std.time.sleep but some area in std.io still uses it? Compile error?

The current implementation in kristoff's PR would make this a compile error, unless compiled with fallow-deprecated. I think this behavior is desirable as it is more consistent.

If zig is to prioritize maintainable software, I disagree. For a library author to provide assurances of backward compatibility, they will need a way to test for it. This includes maintaining tests of their own deprecated code, to ensure no regressions.

It is true that a library author could do a maneuver like this to avoid the problem:

(as mentioned by kristoff-it in this stream)

pub fn sleep() void {
    @deprecated()

    sleepDeprecated()
}


fn sleepDeprecated() void {
    ...
}

where the library author now switches to using sleepDeprecated internally. But I see this as added friction for maintaining deprecated APIs. Maintaining code through deprecation cycles is one of the more difficult problems (just look at LLVM's API regressions that Zig must deal with). Why should Zig make this harder?

This still has the following problems:

1. You cannot directly test your deprecated API's (without the flag), and thus cannot programmatically enforce backwards compatibility.
2. If you must run tests of your own deprecated API's with the flag, you cannot know when your own deprecated code has begun calling your dependencies deprecated APIs (the flag hides this from you).
3. Zig is nudging you to quickly withdraw maintenance effort for your own deprecated APIs.

And has the following pros:

1. A large team working on a library can be assured they are not calling their own deprecated APIs going forward. I don't see this as convincing. It is more important to ensure backwards compatibility for the user than to assist internal development consistency.

This begs the question of "what is deprecated code":

1. If "deprecated" = "code the library author wishes to stop maintaining immediately", the current behavior is desirable. Zig should rapidly push the library author to removing all uses of their own deprecated APIs.
2. If "deprecated" = "code the library author must still maintain, all the way up to the next major release", then the behavior should be changed to allow a library to call their own deprecated code.

I view "deprecated" as still mandating maintenance, up until the next major release.

[nektro]

i dont think those definitions are mutually exclusive. if code is marked deprecated, it should be moved off of immediately (even internally) as it is pending imminent deletion next release cycle and the only code calling it should be its tests.

[kj4tmp]

and the only code calling it should be its tests.

• Build system does not expose an option to set this flag.

As it stands now, if a library author must test their own deprecated code, they will need a bash script to invoke the zig compiler twice, for the entirety of the rest of their release cycle (release cycles can be ~years).

zig build -fallow-deprecated test-all-my-deprecated-stuff
zig build test-but-dont-test-all-my-deprecated-stuff

[rohlem]

If I understand the concern of testing deprecated functions correctly,
we could achieve the desired flexibility by exposing some form of
@allowDeprecated(); or std.testing.allowDeprecated(true);
to mark these known-deprecated test cases with.
(If this was purely a userland mechanism, implementing the latter would be rather trivial.)
Since the only use case are test blocks, calls from elsewhere are forbidden.

Then we could have another flag to allow tests using this mechanism (otherwise we error).
(I think for simplicity, deprecated functions in one package should
transitively be allowed to call deprecated functions in other packages in this mode.)

[andrewrk]

if it's not a nail, don't hit it with a hammer

[andrewrk]

landed in dea72d1

[andrewrk]

Reverted in 6b6c1b1

[Lking03x]

Hi, I'm tinkering around a proposal that aim to solve this issue and many others (distinct types, comptime interface specification, ATS-inspired linear type to track resource usage and cleanup, ...)

It's an annotation system for Zig which would allow, among other things, to add constraints, like the ones required by the compiler, yet implemented in user land.

These would be created at comptime like const deprecated = annotation { ... }. For the user It would be just like an add-on over the type system (no runtime overhead). And the annotation system can provide information about the code to external tools such as LSPs.

Example for the current issue:

const deprecated = @import("std").annotations.deprecated;

#deprecated(.{ .message = "use `bar` instead", .strict = true })
pub fn foo() T {
	// ...
}

With strict set to true one cannot use the deprecated declaration UNLESS:

#allowDeprecated(.{ .foo }) // apply to the current container/scope

// Or in an expression, annotations are use as a pre-fix operator
const baz = if (a_build_constant) #useDeprecated foo() else bar();

Since the annotation system would allow the build script (and external tools) to scan the code for specific conditions, It would thus be possible to forbid the use of deprecated api even if allowDeprecated is used. Or just have a custom build step that list such uses.

This is just an exergue of the desired capabilities concerning this issue, I will provide a more in-deep proposal of the feature at a future time.