allow for a metadata table in a Package.toml in a registry and have a deprecated sub-table indicate the package is deprecated

[KristofferC]

These packages will not tab complete to and will show up as deprecated in pkg status. The [deprecation] table can have arbitrary keys but Pkg itself does not use any of them right now.

Fixes #2194

cc @oxinabox

[tecosaur]

I like this. One thought: is it worth having the optional ability to suggest a different package as a successor? I'm thinking this could be useful in cases like LightGraphs → Graphs (rename), JSON2 → JSON3 (breaking new version as new package), PushVectors → Julia 1.11+ (functionality now available in Julia), etc.

[KristofferC]

The [deprecation] table can have arbitrary keys but Pkg itself does not use any of them right now.

So yes, there is a possibility to add something like a successor or a reason for deprecation or whatever. But for the initial PR I didn't want to spend too much time thinking about exactly what metadata should be included or how it should be presented.

But I guess "reason" and "alternative" could be "standard" keys to have.

[tecosaur]

But for the initial PR I didn't want to spend too much time thinking about exactly what metadata should be included

Entirely reasonable. Attaching some sort of brief message is the only thing I can think of beyond just having a list of packages. Whether it be now or some point in the future, I think just having one free-form field might suffice (predicated on the main way the message is used being shoving it in package developers' faces, I don't think automated tooling would need to know anything more than "package X is deprecated").

[DilumAluthge]

I personally would prefer a more general solution for metadata (or "tags", as Eric has suggested) in the registry (cc: @ericphanson @mbauman), instead of just having syntax specific for package deprecation only.

[KristofferC]

How is this not "general"? It is just a key in the TOML file. Other metadata would have other keys. Or am I missing something?

[mbauman]

Yeah, but it's a good motivating example, because it's quite clear that the additional metadata beyond the deprecated "tag" would be quite valuable. I kinda like aggregating all these sorts of "informational" metadata into single top-level key, but this means that it's something more complicated than the simple tags = ["deprecated"].

[ericphanson]

This is also per package, whereas some metadata should probably be per-version

[KristofferC]

Yeah, but it's a good motivating example, because it's quite clear that the additional metadata beyond the deprecated "tag" would be quite valuable. I kinda like aggregating all these sorts of "informational" metadata into single top-level key, but this means that it's something more complicated than the simple tags = ["deprecated"].

I am a bit confused but do I understand it right that if I call this table metadata.deprecated, it is good because you want it all to be under one big table?

Metadata for versions would presumably go into the Versions.toml file (where there already is "metadata" like yanked). Do you also want it to be metadata.yanked and have that itself be a table (instead of a key-value entry as it is now)?

[mbauman]

I’m not necessarily against it, just trying to think through the relative benefits of this vs something different. It just feels like commingling (potentially) arbitrary tag names alongside semantically meaningful key names will cause us headaches in the future.

[KristofferC]

I'm fine putting it within a metadata table. One reason for making the manifest v2 format was that we earlier had package names as primary keys, which made it hard to add extra stanzas, so there is arguably some precedence there.

[mbauman]

Yeah, I think it'd seem prudent to add an extra level of nesting here. Then there's a choice — this could either be an array of tables or a table of tables. That is, either:

[[metadata]]
name = "deprecated"
reason = "This package is no longer maintained"
alternative = "Example"

[[metadata]]
name = "special"

Or:

[metadata.deprecated]
reason = "This package is no longer maintained"
alternative = "Example"

[metadata.special]

I think I slightly favor the table of tables. And I think I may slightly prefer the name tags to metadata, but that's real bikesheddy.

[KristofferC]

I think I slightly favor the table of tables

Me too, 100%

[KristofferC]

Last commit makes that change

[KristofferC]

added docs as well

[DilumAluthge]

I think I slightly favor the table of tables. And I think I may slightly prefer the name tags to metadata, but that's real bikesheddy.

I'm a little worried that "tags" might make people think of Git tags, but that might not be enough of a problem to justify using the longer "metadata".

[KristofferC]

FWIW I also think metadata is more apt.

[ericphanson]

I think metadata seems reasonable, that also leaves room if we want metadata.tags to be something more specific later

[KristofferC]

[DilumAluthge]

I like the way it suggests a different package to use.

Idea: Instead of just suggesting ModernExample, could we suggest a specific version range for ModernExample?

As a real-world example:

JSON2 vX.Y.Z [deprecated] (Reason: This package is no longer maintained) (Alternative: JSON >= v1.0.0)

Because in this example, we wouldn't want users to inadvertently install an older version of JSON.jl.

This might be too much added complexity, though.

[DilumAluthge]

Another idea: If isinteractive() is true, and if the user uses the REPL interface to do ] add DeprecatedPackage, could we print a warning, or even prompt the user for confirmation?

[KristofferC]

even prompt the user for confirmation?

A prompt has the risk to become annoying, and we already print the [deprecated] in the status output that is shown on add. But a "bigger" warning could be printed on a direct pkg add. But maybe in a follow up PR.

[mbauman]

I don't understand this change?

[KristofferC]

It's just a completely bogus entry, the Deps.toml file don't have compat info like that. It has name -> uuid entries, e.g.:

https://github.com/JuliaRegistries/General/blob/master/A/AAindex/Deps.toml

I guess nothing read that file before.