how to deal with API changes?

[kaspar030]

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?

[miri64]

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

[miri64]

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

[OlegHahm]

Optimist. ;-)

[LudwigKnuepfer]

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"
...

[stale]

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.

[kaspar030]

• mailing lists are notified on API changes now
• no activity on the discussion for technical measures

closing for now.