deprecation: add a file to gather all deprecation notices

Signed-off-by: Tomasz Zawadzki <tomasz.zawadzki@intel.com>
Change-Id: I66e442c4d10c1d40f4d9240f4f48374fc6966f29
Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/6591
Reviewed-by: Jim Harris <james.r.harris@intel.com>
Reviewed-by: Ben Walker <benjamin.walker@intel.com>
Reviewed-by: <dongx.yi@intel.com>
Tested-by: SPDK CI Jenkins <sys_sgci@intel.com>
Community-CI: Mellanox Build Bot

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
+SPDK. The pkg/spdk.spec is considered to be deprecated and scheduled for removal in SPDK 21.07.
-[RPM documentation](https://spdk.io/doc/rpm.html) for more details.
+See [RPM documentation](https://spdk.io/doc/rpm.html) for more details.
 
 ### sock
 

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.

doc/Doxyfile

@@ -813,6 +813,7 @@ INPUT                  += \
                          compression.md \
                          concurrency.md \
                          containers.md \
+                         ../deprecation.md \
                          event.md \
                          ftl.md \
                          gdb_macros.md \

doc/intro.md

@@ -4,4 +4,5 @@
 - @subpage getting_started
 - @subpage vagrant
 - @subpage changelog
+- @subpage deprecation
 - [Source Code (GitHub)](https://github.com/spdk/spdk)