Update on Support Policy for Deprecated API Elements

[zulinx86]

Dear community,

We introduced the API support policy with Firecracker v1.0.0. During the recent deprecation activities, we realized that we have an opportunity to simplify and clarify the rules which we follow to remove deprecated API elements. This discussion aims to inform users and gather their feedback on proposed changes.

Current support policy for deprecated API elements

As stated in the the release policy, Firecracker uses semantic versioning 2.0.0 for its releases, while we don’t use solely it for its API. In case of deprecation of API elements, we also apply the following rules:

### Deprecation of elements in the API

We will consider a deprecated API endpoint to be an endpoint which still has
backing functionality and can be used, but will be removed completely along
with said functionality in an upcoming API version. All deprecated endpoints
are supported until at least the next MAJOR version release, where they _may
be removed_.

When elements of the API are deprecated in a MINOR release, they will still
work for the longest of the following:

* all subsequent Firecracker MINOR releases of the same MAJOR release;
* any Firecracker MINOR release for at least 6 months from release date;
* the next 2 Firecracker releases, regardless if they are MAJOR or MINOR.

Of the three bullet points in the second paragraph, the first and second ones are inherently satisfied under semantic versioning 2.0.0 and the support policy for Firecracker releases. The last condition does not provide clearer information on the actual support time interval compared the rules specified in the release policy.

New support policy for deprecated API elements

To simplify the policy, we have decided to remove the second paragraph, and instead use semantic versioning 2.0.0 also for deprecation and removal of API elements. We intend to update the paragraph as follow:

### Deprecation of elements in the API

Firecracker uses [semantic versioning 2.0.0](https://semver.org/spec/v2.0.0.html)
in terms of deprecating and removing API elements. We will consider a deprecated
API element to be an element which still has backing functionality and will be
supported at least until the next MAJOR version, where they _may be removed_.
The support period of deprecated API elements is tied with
[the Firecracker release support](https://github.com/firecracker-microvm/firecracker/blob/main/docs/RELEASE_POLICY.md#release-support).

Note that we will support deprecated API elements for at least one year, because:

1. a new MINOR version including the deprecation should be issued
2. the latest MINOR version for each MAJOR version will be supported for a year

according to semantic versioning 2.0.0 and our release support policy.

Should you have any questions, concerns or suggestions, please feel free to interact in this discussion. We will create a PR to preview the suggested changes in one week to facilitate the discussion again.

Sincerely,
The Firecracker team

[BinSquare]

It's not clear to me what this means: will be supported at least until the next MAJOR version, where they _may be removed_

How/when will FC team notify if there is certainty around the removal?

Also will there be a migration guide available?

[xmarcalx]

Hi @BinSquare ,

Thanks for the questions.

To answer to your first 2 questions and to clarify the statement:
the safest option for our customers is to assume that a deprecated API element will be always removed in a new MAJOR release as specified in semver 2.0.0. We can substitute "may" with "will" if makes it more clear. We used the "may" just because for unexpected reasons which we can not predict now, we may need to carry on the deprecated elements also in the new MAJOR release too, but that is going to be an exception instead of the general rule.

To answer your last question: yes, whenever we deprecate or delete an element we cite it in our changelog, we document the alternative and we facilitate with example and documentation the usage of the new ones. You can look as example the other discussion on deprecation of static CPU templates where we tried to smooth the transition to custom CPU templates creating equivalent versions of the previous CPU template and dedicated doc to explain how to use the new API.

Let me know if we answered to your questions.

Regards,
Marco

[zulinx86]

I created PR #4181 and should have kept it open to preview the change and facilitate the discussion, but I've merged it into main mistakenly. I'm so sorry :( We're still welcoming any comments on this discussion and the PR #4181 until 23th Oct, so feel free to leave any comments on either.

Best regards,
Takahiro

[zulinx86]

2 weeks have passed since this announcement and the change has got merged into main in PR #4181, so closing this discussion. If you have any questions about the new policy in place, feel free to ask!