Deprecation

Guide to deprecating Q-CTRL software

Deprecation policy

All Q-CTRL software should be evaluated regularly to ensure that it is still required, and if it isn’t, then take the appropriate steps to deprecate it. This document serves as general guidance for the steps required to deprecate Q-CTRL software.

Automatic deprecation

Automatic deprecation is to ensure that Q-CTRL software and its documentation remains maintained throughout their lifecycle. If there seems to be a need for the software, but it is considered deprecated according to this policy, then this might be a good opportunity to make some changes to the repository or update the package to ensure it remains maintained.

Repositories

A repository should be considered deprecated if:

There have been no commits by contributors to the repository for six months.

Packages

A package should be considered deprecated if:

There have been no releases of the package for 12 months.

API elements

An API element should be considered deprecated if:

Is currently in production but we will no longer support its usage.

Deprecation steps

Most deprecations will follow these general steps:

Evaluate whether the software is still required.
Find out all components that the software is used in.
Create a deprecation strategy based on the type of software and the impact of deprecating it.
Implement the strategy.

Depending on what is being deprecated, the steps might vary. For example, deprecating a client package may require adding a deprecation message that points them to new software and a final release, while deprecating a repository might just require a change in the README.md.

Some examples are shown below. Note that the general steps above should still be followed at a high level.

Deprecating a client package

Add the package deprecation notice.
Make any changes to the client that will notify the user of the deprecation.
Release the package as a new MINOR version noting the deprecation in the release notes.
Deprecate the repository.
After 12 months have passed, delete the package.

Deprecating a repository

Add the repository deprecation notice.
Archive the repository.
Back up the repository to external storage if needed.

Deprecating an API element

For publicly used API elements, a communication strategy is required and the removal date must comply with existing customer agreements.
Add a deprecation message to the deprecated element in the standard way for the language or framework being used. This message must be visible by the API clients.
Add a logging message at warning level to provide visibility when the deprecated element is used.
After reaching the removal date and handling all internal usage the element can be removed.

Templates

Package deprecation notice

Use this at the top of README.md.

# ⚠️ (DEPRECATED) This package has been deprecated ⚠️

Include any extra relevant information for the user of this package. Do not include internal developer information.

Repository deprecation notice

Use this at the top of .github/README.md.

# ⚠️ (DEPRECATED) This project has been deprecated ⚠️

Include any extra relevant information if needed. Note that this is what will be viewed in the README.md section on the repository's home page.

API element deprecation notice

All deprecation notices for an API element must include a reason for the deprecation and a date when support will end. The way deprecation notices are added to code may vary considerably based on the programming language, framework or API standard used.

This is an example deprecating a GraphQL query:

CustomType {
 id: ID
 summary: String
 tags: [String] @deprecate(reason:"use labels | removalDate: 2023-05-01")
 labels: [String]
}

And this is its related resolver using Python and Ariadne:

custom_type = ObjectType("CustomType")

@tenant_type.field("tags")
def resolve_tags(obj: CustomType, _) -> EnvironmentSpecs:
    """Resolve environmentSpecs field."""
    logging.warning("Deprecated: `CustomType.tags`. Reason: `use labels`. Removal Date: `2023-05-01`")
    return obj.tags

On this page