Add ability to deprecate and undeprecate repositories

[bufdev]

We've already gotten to the point where we want to make it clear to users that a module they depend on has been deprecated (with the beta org repositories). It would be useful to be able to set this in the module buf.yaml file.

For reference, Go 1.17 released this as a first-class feature of the Go modules ecosystem: https://golang.org/doc/go1.17#go-command.

-- edit --

This changed to using the command line to deprecate and undeprecate repositories with buf beta registry repository [un]deprecate.

Shipped in #638

[amckinney]

There are a couple things to consider here.

Although Go went with the // Deprecated: … comment approach, they didn’t really have any other options. Go modules are inherently decentralized - they can’t configure the GitHub repository that contains the module and deprecate it there since the module isn’t guaranteed to exist in a GitHub repository. With things like the Go module proxy, they need a way to determine if the module is deprecated with the module content alone (hence tying it to the go.mod).

Modules stored in the BSR, on the other hand, are centralized. With that said, we can make deprecation a property of the BSR repository instead of the module’s buf.yaml configuration. All operations that interact with modules go through the module’s repository, and deprecation will always be enforced there. For example, if I update my dependencies, the BSR will know whether or not the module is deprecated because it would be a property of the repository.

This has a couple benefits:

1. [Un]Deprecating a module doesn’t require an additional commit with (potentially) the same file content (i.e. with buf push --force). Users simply navigate to their repository and toggle deprecation on or off.
2. We don’t have to support any new configuration fields in buf.yaml.

It’s worth noting that this makes it harder to deprecate individual commits: either the repository (and all of its commits) are deprecated, or not (Go supposedly does the same for all minor versions of the module). However, this might actually be a feature: deprecation almost always means that any use of this module should be replaced with something else (e.g. buf.build/beta/googleapis and buf.build/googleapis/googleapis). With that said, we shouldn’t need to let users deprecate individual commits - their consumers should always just use the latest commit available to them anyway. If a module author wants to un-deprecate their module, they can simply toggle the setting on their repository and instruct their consumers to use the latest version.

With all that said, I'm not totally opposed to including adding a buf.yaml option for this - I'm just not convinced it's necessary given the nature of the BSR.

[doriable]

Some thoughts I have here:

1. [Un]Deprecating a module doesn’t require an additional commit with (potentially) the same file content (i.e. with buf push --force). Users simply navigate to their repository and toggle deprecation on or off.
2. We don’t have to support any new configuration fields in buf.yaml.

I think that deprecation should pertain to the module entity, and I'm inclined to agree that in this case, it is best served at the repository level, since it doesn't require mutating the module with an additional commit. That being said, this does not really change local dependency behaviours, but if our stance on dependencies is that "we don't care what you depend on in your local state, we simply do not want you to resolve this remote dependency", then I think that is acceptable.

It’s worth noting that this makes it harder to deprecate individual commits: either the repository (and all of its commits) are deprecated, or not (Go supposedly does the same for all minor versions of the module).

I think this is the "correct behaviour" -- to me "deprecating" an individual commit is actually "blacklisting" that commit. "Deprecation" implies that the entire entity is no longer supported or managed, whereas deterring users from depending on a specific commit usually implies that the specific commit has an issue (e.g. a breaking change was pushed and then reverted, etc.). I think we should separate that into its own user experience.

[doriable]

I've added this task to both the BSR and Research projects, since based on the discussions, if we are adding this flag at the repository level, it would be part of the BSR, however, since this is still very much tied to the dependency management experience, I didn't want to remove it from Research.

[amckinney]

This was released in https://github.com/bufbuild/buf/releases/tag/v1.0.0-rc5