Deprecated packages

[sameerajayasoma]

In the early days, we designed Ballerina package repositories to be immutable, but the current package repositories didn’t implement this concept fully. E.g., It was allowed to delete packages in Ballerina central until recently.

There are situations where package authors want to prevent users from using specific package versions. E.g., packages with serious bugs. The build command auto upgrades package versions to the latest patch version, and if the latest patch version is broken, that can cause build breaks in every user program using that package. We came across this situation a few weeks ago. The quick way to resolve such a case is to delete the package, but doing so can create more issues.

Therefore, I propose introducing a way to mark a complete package, specific package version, or a package version range as deprecated.

Here are the semantics of a deprecated package:

• If a deprecated dependency version is already recorded in a Dependencies.toml of a package, builds of that package will continue to work with a warning.
• A deprecated dependency version will not be recorded as a new dependency in a Dependencies.toml file unless there are no other versions that can satisfy dependency requirements. If the dependency resolver used a deprecated package version, there would be a warning in the build log.
• No new packages with deprecated dependencies can be pushed to a package repository(Ballerina Central).

[sameerajayasoma]

If you, as the package author, had to mark the latest patch version of a package as deprecated, we recommend pushing a new version as soon as possible.

[sameerajayasoma]

I can think of two ways to mark a package as deprecated:

• Via the Ballerina central UI (This will only work with Ballerina central)
• The more general approach would be to introduce a new bal command. bal deprecate or bal pkg deprecate. This will work for any package repository

[chalitha1989]

What can I do if I accidentally publish a package with a secret? Also package lifecycle ends after the depreciation? Can the user retire, or delete the package after sometime?

[sameerajayasoma]

@chalitha1989, I would immediately revoke the secrets. I am not suggesting deleting the package. Once published, it'll be there forever :)

[chalitha1989]

@chalitha1989, I would immediately revoke the secrets. I am not suggesting deleting the package. Once published, it'll be there forever :)

This is basically an accidental push. The secret (let's say sensitive info) can be a non revokable config such as an email address, user detail, URL(DB, backend) etc. Yes, revoking can be done when required but the issue is the existence of the package. I don't won't to keep a package published, knowing that I have accidentally published some sensitive information with it.

[anupama-pathirage]

@sameerajayasoma We don't have a staging capability for a package. So how a package author can test their package and delete it if it is having some issues? So shouldn't we bring the allow delete packages until staging packages are allowed?

[anuruddhal]

@chalitha1989 For accidental push, we can use the existing email-based approach. The Central team can guarantee an SLA to remove the package after sending an email.

[sameerajayasoma]

Here are the revised semantics of a deprecated package:

Deprecated package d will not be part of the dependency graph of package p except in the following situations:

• d is recorded as a dependency in p's Dependencies.toml, and the --sticky option is used to build p.
• d is the only compatible version available in the local cache, and the --ofline option is used to build p.
• No other versions of d can satisfy the dependency requirements of p.

A warning MUST be issued if d is used as part of the dependency graph of p.

[sameerajayasoma]

bal pull

• Allows pulling a deprecated package but prints a warning to the console.
• Allows pulling a package that has deprecated package dependency but prints a warning to the console.

bal push

• Does not allow pushing a package that has a deprecated package dependency

[sameerajayasoma]

Ballerina central UI will introduce a capability to deprecate/undeprecate packages via Central UI. In addition to that, we decided to introduce bal deprecate command.

NAME
    ballerina-deprecate - Deprecates a published package

SYNOPSIS
    bal deprecate [OPTIONS] <package>

DESCRIPTION
The deprecate commands marks the specified package as deprecated in Ballerina central. 

A deprecated package will not be used as a dependency of a package unless the deprecated package is already recorded in 
the `Dependencies.toml` and the `--sticky` option is used to build the package. Also, a deprecated package will be used as 
a dependency of a package if there are no other versions that can satisfy dependency constraints. 

A warning diagnostic will be issued whenever a deprecated package is used as a dependency.

This command does not delete the package from Ballerina central, and the package can be undeprecated using the `--undo` option. 

OPTIONS
-m <msg>, --message=<msg>
    Use the give <msg> as the deprecation message
-- undo
    Undeprecate a deprecated package

EXAMPLES
Deprecates the package ballerina/io:1.1.1 
    bal deprecate ballerina/io:1.1.1

Deprecates the package ballerina/io:1.1.1 with a message
    bal deprecate ballerina/io:1.1.1 -m “Found a critical security issue, use 1.1.2 instead”

[hevayo]

What will be the use of deprecate message. We can store it in central and display with the deprecated package. Also we can warn users with this message if they are dependent on a deprecated package.

Also I assume deprecated versions should be hidden from Central search.

[sameerajayasoma]

We are adding Ballerina package-related commands to the bal command space one by one. We can consider grouping such commands under a sub-command such as bal pkg.

[Dilhasha]

We have implemented the support for deprecating a specific version of a package in central with Swanlake update 5. But, there is a requirement to deprecate a complete package(all of its versions). Please refer to https://github.com/ballerina-platform/ballerina-central/issues/57 for such a requirement.

@sameerajayasoma Shall we introduce the support to deprecate a complete package too?

[azinneera]

We have implemented the support for deprecating a specific version of a package in central with Swanlake update 5. But, there is a requirement to deprecate a complete package(all of its versions). Please refer to ballerina-platform/ballerina-central#57 for such a requirement.

@sameerajayasoma Shall we introduce the support to deprecate a complete package too?

With https://github.com/ballerina-platform/ballerina-lang/pull/40180 we added the support to deprecate an entire package as well.

[sameerajayasoma]

This capability is available in Ballerina now.