Deprecations and API changes

Following semantic versioning, changes to the public facing API of AiiDA require a bump in the major version number.

Gathering usage information

Before deprecating an API or making a change, it is often useful to know how much the API in question is used in practice. Since many AiiDA plugins are hosted on GitHub, GitHub's global code search can come in very handy.

E.g. here is a query to see how much the _get_base_folder function is used in files that also contain the string "aiida":

https://github.com/search?q=%22_get_base_folder%22+aiida&type=Code

Deprecating the CLI

In general the CLI commands can be modified or removed more freely because users should not be relying on them for automated processes, and direct usage can easily be corrected. For this, it is still crucial however to provide with the proper deprecation that indicates how to proceed in the future.

In order to deprecate a CLI command, it is advisable to (1) indicate in the docstring the release in which the deprecation was introduced and (2) decorate the function with the deprecated_command decorator. Here is an example:

@verdi_database.command('version')
@decorators.deprecated_command(
    'This command has been deprecated and will be removed soon. '
    'The same information is now available through `verdi status`.\n'
)
def database_version():
    """Show the version of the database.

    The database version is defined by the tuple of the schema generation and schema revision.

    .. deprecated:: v2.1.0
    """

This decorator can be found in aiida.cmdline.utils.decorators. It is important to note that the decorator must go below the verdi decorator and that only proper click commands have to be decorated, the decorator has no effect on groups of commands.

If the procedure needs to be forwarded to another command, one can use the Context.forward() method (see the click docs for more information).