Merge pull request #1229 from bitcraze/krichardsson/deprecation

Added docs about deprecations

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();
   }
 

docs/development/apis_versions_deprecation.md

@@ -0,0 +1,55 @@
+---
+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. 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. 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
+
+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`
+* [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/)
+* [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/)

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)

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.

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

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);
 }

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)
@@ -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;

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)

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)