Riot: how to deal with API changes?

Created on 3 Jun 2016 · 6Comments · Source: RIOT-OS/RIOT

currently, some (not all) of our API changes are announced on the mailing list, and some (not all) are mentioned in the release notes.

Is there a way to optimize this?

Ideas:

_all_ of the API changes need to be announced on the mailing list, with a clear subject ("API CHANGE in foo_bar()" and a message body explaining how to fix legacy code,
we create a file API_CHANGES in the repo, and all API changing commits contain above information?

Or keep it as is - try to reasonably inform the crowd somehow?

RFC stale

Source

kaspar030

All 6 comments

I'm not sure we need the file, but the announcements to the mailing list are certainly a good idea.

miri64 on 3 Jun 2016

(on the other hand I hope we are getting to a point soonish, where API changes are something that happens rather rarely ;-))

miri64 on 3 Jun 2016

Optimist. ;-)

OlegHahm on 3 Jun 2016

I would suggest versionizing APIs so that users of an API will be notified at compile time when they need to update their code due to an API change.

i.e. something along the lines of (bear with me - untested):
my_api.h

#define MY_API_VERSION 4711
#if MY_API_VERSION_USED != MY_API_VERSION
#error my_api version does not match used version
#endif
...

usercode.c

#define MY_API_VERSION_USED 23
#include "my_api.h"
...

LudwigKnuepfer on 4 Jun 2016

👎2 👍1

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. If you want me to ignore this issue, please mark it with the "State: don't stale" label. Thank you for your contributions.