From 7b218d49b447e013acc1b377a9c0b6bd17812ef3 Mon Sep 17 00:00:00 2001 From: Kristoffer Richardsson Date: Wed, 15 Feb 2023 14:46:24 +0100 Subject: [PATCH 1/2] Added docs about deprecations --- app_api/src/app_main.c | 6 +-- docs/development/apis_versions_deprecation.md | 42 +++++++++++++++++++ src/deck/drivers/src/locodeck.c | 3 +- src/modules/interface/app_channel.h | 6 +-- src/modules/interface/sitaw.h | 2 +- src/modules/src/app_channel.c | 4 +- src/modules/src/crtp_commander_high_level.c | 8 ++-- src/modules/src/crtp_localization_service.c | 2 +- src/modules/src/lighthouse/lighthouse_core.c | 4 +- 9 files changed, 59 insertions(+), 18 deletions(-) create mode 100644 docs/development/apis_versions_deprecation.md diff --git a/app_api/src/app_main.c b/app_api/src/app_main.c index 3c333c676e..eb7912bd4f 100644 --- a/app_api/src/app_main.c +++ b/app_api/src/app_main.c @@ -131,12 +131,12 @@ void appMain() { // App-channel { char buffer[APPCHANNEL_MTU]; - appchannelSendPacket("hello", 5); // Deprecated + appchannelSendPacket("hello", 5); // Deprecated (removed after August 2023) appchannelSendDataPacketBlock("hello", 5); appchannelSendDataPacket("hello", 5); - appchannelReceivePacket(buffer, APPCHANNEL_MTU, APPCHANNEL_WAIT_FOREVER); // Deprecated + appchannelReceivePacket(buffer, APPCHANNEL_MTU, APPCHANNEL_WAIT_FOREVER); // Deprecated (removed after August 2023) appchannelReceiveDataPacket(buffer, APPCHANNEL_MTU, APPCHANNEL_WAIT_FOREVER); - appchannelHasOverflowOccured(); // Deprecated + appchannelHasOverflowOccured(); // Deprecated (removed after August 2023) appchannelHasOverflowOccurred(); } diff --git a/docs/development/apis_versions_deprecation.md b/docs/development/apis_versions_deprecation.md new file mode 100644 index 0000000000..c23be39273 --- /dev/null +++ b/docs/development/apis_versions_deprecation.md @@ -0,0 +1,42 @@ +--- +title: APIs, versions and deprecations +page_id: api-deprecation +--- + +There are a number of APIs in the Crazyflie eco system on multiple levels, some might be obvious while others are a bit +more subtle. Some of the APIs are documented and versioned while there is room for improvement in other cases. + +Since all code can be used by a programmer, one point of view would be that all functions and protocols are APIs, and +should not change without some form of version change. To +make it possible for us to manage the code base, we have chosen a few areas (APIs) that we will update in a structured way +(see below). Code that does not belong to these APIs can be changed at any time, which we believe is necessary to keep +the system dynamic and evolve over time. + +The purpose of managing APIs in a structured way is to help a developer to understand if a protocol or a set of +functions is likely to change over time and if it will break the application. It should also be possible to detect if +(and how) the API has changed and what changes that are required to the code to make the application work. + +## The update process and deprecations + +Areas that can be versioned using a version number, for instance protocols, should update the version number when +something (of instance the protocol) is changed. Check the documentation for the specific area/protocol to see if there +is a specific update policy for this area. + +For functions in the code base, there is not really a version number tied to the function (except the release version) that +clearly tells the programmer if there has been an API break or not. The approach we use is to mark functions that we +want to remove as 'deprecated`. The deprecated function will continue to exist and work for a minimum of 6 months before +being removed. Deprecated functions are documented in the release notes to give a heads up that they will be removed in +a future release. + +## Current APIs with structured updates + +The following areas and protocols are updated with a structured process: + +* [CRTP](/docs/functional-areas/crtp) +* App API - the functions called from `app_api/src/app_main.c` +* [Parmeters](/docs/api/params.md) - parameters marked as `CORE` +* [Logs](/docs/api/logs.md) - logs marked as `CORE` +* [Trajectory formats](/docs/functional-areas/trajectory_formats.md) +* [Loco TWR protocol](https://www.bitcraze.io/documentation/repository/lps-node-firmware/master/protocols/twr-protocol/) +* [Loco TDoA2 protocol](https://www.bitcraze.io/documentation/repository/lps-node-firmware/master/protocols/tdoa2_protocol/) +* [Loco TDoA3 protocol](https://www.bitcraze.io/documentation/repository/lps-node-firmware/master/protocols/tdoa3_protocol/) diff --git a/src/deck/drivers/src/locodeck.c b/src/deck/drivers/src/locodeck.c index 811075538b..a025c87c61 100644 --- a/src/deck/drivers/src/locodeck.c +++ b/src/deck/drivers/src/locodeck.c @@ -601,7 +601,8 @@ DECK_DRIVER(dwm1000_deck); PARAM_GROUP_START(deck) /** - * @brief Deprecated, replaced with the "deck.bcLoco" parameter. + * @brief Deprecated (removed after August 2023). Use the "deck.bcLoco" parameter instead. + * * Nonzero if [Loco positioning deck](%https://store.bitcraze.io/products/loco-positioning-deck) is attached */ PARAM_ADD_CORE(PARAM_UINT8 | PARAM_RONLY, bcDWM1000, &isInit) diff --git a/src/modules/interface/app_channel.h b/src/modules/interface/app_channel.h index cc9f49de9c..70b16f03c6 100644 --- a/src/modules/interface/app_channel.h +++ b/src/modules/interface/app_channel.h @@ -34,7 +34,7 @@ #define APPCHANNEL_MTU (31) /** - * Send an app-channel packet - deprecated, use appchannelSendDataPacketBlock() instead + * Send an app-channel packet - deprecated (removed after August 2023). Use appchannelSendDataPacketBlock() instead. * * The maximum buffer size that can be sent is define in APPCHANNEL_MTU. * If the length of the buffer is longer than that, the packet will be cropped @@ -90,7 +90,7 @@ void appchannelSendDataPacketBlock(void* data, size_t length); int appchannelSendDataPacket(void* data, size_t length); /** - * Receive an app-channel packet - deprecated, use appchannelReceiveDataPacket() instead + * Receive an app-channel packet - deprecated (removed after August 2023). Use appchannelReceiveDataPacket() instead * * If the data received is longer than max_length, the data will be silently cropped and only * the fist "max_length" bytes of the packet will be copied in the buffer. @@ -138,7 +138,7 @@ size_t appchannelReceiveDataPacket(void* buffer, size_t max_length, int timeout_ bool appchannelHasOverflowOccurred(); /** - * Returns if an overflow has occurred in the receive queue - deprecated, use appchannelHasOverflowOccurred() instead + * Returns if an overflow has occurred in the receive queue - deprecated (removed after August 2023). Use appchannelHasOverflowOccurred() instead * * The app-channel received packets are put in a queue. It is expected that the app is * regularly calling appchannelReceiveDataPacket() to get the packets from the receive queue. diff --git a/src/modules/interface/sitaw.h b/src/modules/interface/sitaw.h index a1c0f76bde..e43aa329ed 100644 --- a/src/modules/interface/sitaw.h +++ b/src/modules/interface/sitaw.h @@ -26,7 +26,7 @@ #pragma once -#pragma message "sitAwTuDetected is deprecated, consider switching to supervisorIsTumbled!" +#pragma message "sitAwTuDetected is deprecated (removed after August 2023), consider switching to supervisorIsTumbled!" #include "supervisor.h" #define sitAwTuDetected supervisorIsTumbled diff --git a/src/modules/src/app_channel.c b/src/modules/src/app_channel.c index 476987038d..9d2f41a85f 100644 --- a/src/modules/src/app_channel.c +++ b/src/modules/src/app_channel.c @@ -43,7 +43,7 @@ static bool overflow; static int sendDataPacket(void* data, size_t length, const bool doBlock); -// Deprecated +// Deprecated (removed after August 2023) void appchannelSendPacket(void* data, size_t length) { appchannelSendDataPacketBlock(data, length); @@ -59,7 +59,7 @@ void appchannelSendDataPacketBlock(void* data, size_t length) sendDataPacket(data, length, true); } -// Deprecated +// Deprecated (removed after August 2023) size_t appchannelReceivePacket(void* buffer, size_t max_length, int timeout_ms) { return appchannelReceiveDataPacket(buffer, max_length, timeout_ms); } diff --git a/src/modules/src/crtp_commander_high_level.c b/src/modules/src/crtp_commander_high_level.c index eff53dbe72..5ab7378913 100644 --- a/src/modules/src/crtp_commander_high_level.c +++ b/src/modules/src/crtp_commander_high_level.c @@ -129,8 +129,8 @@ STATIC_MEM_TASK_ALLOC(crtpCommanderHighLevelTask, CMD_HIGH_LEVEL_TASK_STACKSIZE) // trajectory command (first byte of crtp packet) enum TrajectoryCommand_e { COMMAND_SET_GROUP_MASK = 0, - COMMAND_TAKEOFF = 1, // Deprecated, use COMMAND_TAKEOFF_2 - COMMAND_LAND = 2, // Deprecated, use COMMAND_LAND_2 + COMMAND_TAKEOFF = 1, // Deprecated (removed after August 2023), use COMMAND_TAKEOFF_2 + COMMAND_LAND = 2, // Deprecated (removed after August 2023), use COMMAND_LAND_2 COMMAND_STOP = 3, COMMAND_GO_TO = 4, COMMAND_START_TRAJECTORY = 5, @@ -146,7 +146,7 @@ struct data_set_group_mask { } __attribute__((packed)); // vertical takeoff from current x-y position to given height -// Deprecated +// Deprecated (removed after August 2023) struct data_takeoff { uint8_t groupMask; // mask for which CFs this should apply to float height; // m (absolute) @@ -174,7 +174,7 @@ struct data_takeoff_with_velocity { } __attribute__((packed)); // vertical land from current x-y position to given height -// Deprecated +// Deprecated (removed after August 2023) struct data_land { uint8_t groupMask; // mask for which CFs this should apply to float height; // m (absolute) diff --git a/src/modules/src/crtp_localization_service.c b/src/modules/src/crtp_localization_service.c index 88fab9b48e..54461c19e1 100644 --- a/src/modules/src/crtp_localization_service.c +++ b/src/modules/src/crtp_localization_service.c @@ -390,7 +390,7 @@ void locSrvSendLighthouseAngle(int baseStation, pulseProcessorResult_t* angles) } #endif -// This logging group is deprecated +// This logging group is deprecated (removed after August 2023) LOG_GROUP_START(ext_pos) LOG_ADD(LOG_FLOAT, X, &ext_pos.x) LOG_ADD(LOG_FLOAT, Y, &ext_pos.y) diff --git a/src/modules/src/lighthouse/lighthouse_core.c b/src/modules/src/lighthouse/lighthouse_core.c index c44efc018d..31dccc4fd8 100644 --- a/src/modules/src/lighthouse/lighthouse_core.c +++ b/src/modules/src/lighthouse/lighthouse_core.c @@ -913,11 +913,9 @@ PARAM_ADD_CORE(PARAM_UINT8, bsCalibReset, &calibStatusReset) PARAM_ADD_CORE(PARAM_UINT8, systemType, &systemType) /** - * @brief Bit field that indicates which base stations that are supported by the system + * @brief Bit field that indicates which base stations that are supported by the system - deprecated (removed after August 2023) * * The lowest bit maps to base station channel 1 and the highest to channel 16. - * - * Deprecated since 2022-08-15 */ PARAM_ADD_CORE(PARAM_UINT16 | PARAM_RONLY, bsAvailable, &baseStationAvailabledMap) From 067c94dbb1e0f5f6f57b999908c95e8e6c72520f Mon Sep 17 00:00:00 2001 From: Kristoffer Richardsson Date: Wed, 15 Feb 2023 16:02:29 +0100 Subject: [PATCH 2/2] Clarifications --- docs/development/apis_versions_deprecation.md | 19 ++++++++++++++++--- src/modules/src/crtp_commander_high_level.c | 2 ++ 2 files changed, 18 insertions(+), 3 deletions(-) diff --git a/docs/development/apis_versions_deprecation.md b/docs/development/apis_versions_deprecation.md index c23be39273..63cc7cbd6d 100644 --- a/docs/development/apis_versions_deprecation.md +++ b/docs/development/apis_versions_deprecation.md @@ -20,13 +20,26 @@ functions is likely to change over time and if it will break the application. It Areas that can be versioned using a version number, for instance protocols, should update the version number when something (of instance the protocol) is changed. Check the documentation for the specific area/protocol to see if there -is a specific update policy for this area. +is a specific update policy for this area. An example would be [CRTP](/docs/functional-areas/crtp/index.md#protocol-version-and-stability-guarantee). For functions in the code base, there is not really a version number tied to the function (except the release version) that clearly tells the programmer if there has been an API break or not. The approach we use is to mark functions that we want to remove as 'deprecated`. The deprecated function will continue to exist and work for a minimum of 6 months before being removed. Deprecated functions are documented in the release notes to give a heads up that they will be removed in -a future release. +a future release. The deprecation marking is usually done by adding the word `deprecated` to the function documentation. +Also add a date when the function will be removed (at the earliest) and, if applicable, a replacement function to use +instead. + +Example: + +``` C +/** + * @brief Deprecated (removed after August 2023). Use the "deck.bcLoco" parameter instead. + * + * Nonzero if [Loco positioning deck](%https://store.bitcraze.io/products/loco-positioning-deck) is attached + */ +PARAM_ADD_CORE(PARAM_UINT8 | PARAM_RONLY, bcDWM1000, &isInit) +``` ## Current APIs with structured updates @@ -34,7 +47,7 @@ The following areas and protocols are updated with a structured process: * [CRTP](/docs/functional-areas/crtp) * App API - the functions called from `app_api/src/app_main.c` -* [Parmeters](/docs/api/params.md) - parameters marked as `CORE` +* [Parameters](/docs/api/params.md) - parameters marked as `CORE` * [Logs](/docs/api/logs.md) - logs marked as `CORE` * [Trajectory formats](/docs/functional-areas/trajectory_formats.md) * [Loco TWR protocol](https://www.bitcraze.io/documentation/repository/lps-node-firmware/master/protocols/twr-protocol/) diff --git a/src/modules/src/crtp_commander_high_level.c b/src/modules/src/crtp_commander_high_level.c index 5ab7378913..5f653287b4 100644 --- a/src/modules/src/crtp_commander_high_level.c +++ b/src/modules/src/crtp_commander_high_level.c @@ -433,6 +433,7 @@ int set_group_mask(const struct data_set_group_mask* data) return 0; } +// Deprecated (removed after August 2023) int takeoff(const struct data_takeoff* data) { int result = 0; @@ -488,6 +489,7 @@ int takeoff_with_velocity(const struct data_takeoff_with_velocity* data) return result; } +// Deprecated (removed after August 2023) int land(const struct data_land* data) { int result = 0;