From 9a3877213e9c26ace942f932fc6e23a4d3fe366e Mon Sep 17 00:00:00 2001 From: Tomasz Zawadzki Date: Fri, 26 Feb 2021 07:33:12 -0500 Subject: [PATCH] deprecation: add a file to gather all deprecation notices Signed-off-by: Tomasz Zawadzki Change-Id: I66e442c4d10c1d40f4d9240f4f48374fc6966f29 Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/6591 Reviewed-by: Jim Harris Reviewed-by: Ben Walker Reviewed-by: Tested-by: SPDK CI Jenkins Community-CI: Mellanox Build Bot --- CHANGELOG.md | 6 +++--- deprecation.md | 35 +++++++++++++++++++++++++++++++++++ doc/Doxyfile | 1 + doc/intro.md | 1 + 4 files changed, 40 insertions(+), 3 deletions(-) create mode 100644 deprecation.md diff --git a/CHANGELOG.md b/CHANGELOG.md index e366e4b86..b4443da77 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -121,7 +121,7 @@ Added new APIs: - `spdk_nvmf_poll_group_dump_stat` (function in `nvmf.h`). - `poll_group_dump_stat` (transport op in `nvmf_transport.h`). -The following APIs have been deprecated and will be removed in a future release: +The following APIs have been deprecated and will be removed in SPDK 21.07: - `spdk_nvmf_poll_group_get_stat` (function in `nvmf.h`), - `spdk_nvmf_transport_poll_group_get_stat` (function in `nvmf.h`), @@ -164,8 +164,8 @@ of nvme poll groups. ### rpm Added support for new RPM spec, rpmbuild/spdk.spec, which can be used for packaging the -SPDK. The pkg/spdk.spec is considered to be deprecated and scheduled for removal. See -[RPM documentation](https://spdk.io/doc/rpm.html) for more details. +SPDK. The pkg/spdk.spec is considered to be deprecated and scheduled for removal in SPDK 21.07. +See [RPM documentation](https://spdk.io/doc/rpm.html) for more details. ### sock diff --git a/deprecation.md b/deprecation.md new file mode 100644 index 000000000..af5e595d8 --- /dev/null +++ b/deprecation.md @@ -0,0 +1,35 @@ +# ABI and API Deprecation {#deprecation} + +This document details the policy for maintaining stability of SPDK ABI and API. + +Major ABI version can change at most once for each quarterly SPDK release. +ABI versions are managed separately for each library and follow [Semantic Versoning](https://semver.org/). + +API and ABI deprecation notices shall be posted in the next section. +Each entry must describe what will be removed and can suggest the future use or alternative. +Specific future SPDK release for the removal must be provided. +ABI cannot be removed without providing deprecation notice for at least single SPDK release. + +# Deprecation Notices {#deprecation-notices} + +## net + +The net library is deprecated and will be removed in the 21.07 release. + +## nvmf + +The following APIs have been deprecated and will be removed in SPDK 21.07: +- `spdk_nvmf_poll_group_get_stat` (function in `nvmf.h`), +- `spdk_nvmf_transport_poll_group_get_stat` (function in `nvmf.h`), +- `spdk_nvmf_transport_poll_group_free_stat`(function in `nvmf.h`), +- `spdk_nvmf_rdma_device_stat` (struct in `nvmf.h`), +- `spdk_nvmf_transport_poll_group_stat` (struct in `nvmf.h`), +- `poll_group_get_stat` (transport op in `nvmf_transport.h`), +- `poll_group_free_stat` (transport op in `nvmf_transport.h`). +Please use `spdk_nvmf_poll_group_dump_stat` and `poll_group_dump_stat` instead. + +## rpm + +`pkg/spdk.spec` is considered to be deprecated and scheduled for removal in SPDK 21.07. +Please use `rpmbuild/spdk.spec` instead and see +[RPM documentation](https://spdk.io/doc/rpm.html) for more details. diff --git a/doc/Doxyfile b/doc/Doxyfile index 98220305f..7ecc216aa 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -813,6 +813,7 @@ INPUT += \ compression.md \ concurrency.md \ containers.md \ + ../deprecation.md \ event.md \ ftl.md \ gdb_macros.md \ diff --git a/doc/intro.md b/doc/intro.md index ebae8d454..5dcfee24e 100644 --- a/doc/intro.md +++ b/doc/intro.md @@ -4,4 +4,5 @@ - @subpage getting_started - @subpage vagrant - @subpage changelog +- @subpage deprecation - [Source Code (GitHub)](https://github.com/spdk/spdk)