Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added docs about deprecations #1229

Merged
merged 2 commits into from
Feb 15, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions app_api/src/app_main.c
Original file line number Diff line number Diff line change
Expand Up @@ -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();
}

Expand Down
55 changes: 55 additions & 0 deletions docs/development/apis_versions_deprecation.md
Original file line number Diff line number Diff line change
@@ -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/)
3 changes: 2 additions & 1 deletion src/deck/drivers/src/locodeck.c
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
6 changes: 3 additions & 3 deletions src/modules/interface/app_channel.h
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion src/modules/interface/sitaw.h
Original file line number Diff line number Diff line change
Expand Up @@ -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
4 changes: 2 additions & 2 deletions src/modules/src/app_channel.c
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand All @@ -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);
}
Expand Down
10 changes: 6 additions & 4 deletions src/modules/src/crtp_commander_high_level.c
Original file line number Diff line number Diff line change
Expand Up @@ -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
krichardsson marked this conversation as resolved.
Show resolved Hide resolved
COMMAND_LAND = 2, // Deprecated (removed after August 2023), use COMMAND_LAND_2
COMMAND_STOP = 3,
COMMAND_GO_TO = 4,
COMMAND_START_TRAJECTORY = 5,
Expand All @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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;
Expand Down
2 changes: 1 addition & 1 deletion src/modules/src/crtp_localization_service.c
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
4 changes: 1 addition & 3 deletions src/modules/src/lighthouse/lighthouse_core.c
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down