4

Let's say I have a API with regular updates and many developer who are using the API. Whenever the API updates I don't want to bother the developers with all the change updates. I want to send them updates about only the functions or classes that they are using in their code.

I have a faint idea, but not sure if this would work.

  1. A service which will have an index of all the changes made to the files functions based on the git commits in the last day.
  2. A module or plugin on the client side(where the API resides) which will check with this service on a cron run regarding the changes made to the API, compare it with its internal index of files and functions used and send updates to the developer if there is a match.

Is there something implemented on these lines already? If not what would be the right way to go forward.

Improve this question
3
  • What is your reason for not wanting to bother the developers using the API with all the change updates? Commented Aug 5, 2015 at 6:20
  • There can be many updates and it might be too much of noise. I think they would be more willing to check and update their implementations if they get context specific updates. Commented Aug 5, 2015 at 6:33
  • 3
    If I was the developer on the receiving end, I think the most useful thing to me personally would be having multiple changelists, showing the same set of changes but organized differently so I can search the information however I want. For instance, one list organized by issue/feature/bugfix/etc (in case I've been waiting for specific tickets to get resolved), and another list organized by module/class/function/etc (so I can look for the parts I personally use, or might be interested in using) would be very nice. Nicer than an automated tool imo. Commented Aug 5, 2015 at 6:54

2 Answers 2

Reset to default
1

I guess you are talking about a system where you have access to the complete source code of all developers involved, and it is all within one organization, right?

I do not think this will work well on the API level, you have to do something like this on the component/module/library level. Even if you do not change the API syntactically, internal changes in a library can affect the code of everyone using that library (and the only way to make sure your changes did not break anything is to do or execute enough tests). However, if you know a program or module does not reference another component/module/library, then a change there cannot break it easily.

So a better way is to have your changes (semantically and syntactically) documented on a per-module basis. And to inform the right developer actively, the ones which might be affected by a change in a specific module (and noone else), you need two things:

  • a reference graph, wich application or module is using/referencing/linking which other module

  • a list of who is responsible for each module

(and assumed you have those documents, it should be clear how to use them).

For the reference graph of modules, depending on the size of the system and the used programming language ecosystem, you can either maintain that manually, try to find some tools for cross reference generation, or implement a reference scanner manually (maybe in some kind of scripting language). The second one is probably best maintained manually.

Improve this answer
1

I would consider this to be a solution in search of a problem. I've never seen developers care that a changelog contains extra information - they fall into 2 broad groups, those who don't read the changelog anyway and those who read it all to see what's been happening.

What you can do is make the changelog easier to read and parse.

I would simply categorise the changes in each release, possibly by including the API function or class or area that is changes, and mark bugs or features. eg. Jenkins changelog has coloured dots for butgs, features, major bugs etc so you can see at a glance if an update can be ignored or needs to be applied soon. Boost's changelog has groups for bugfixes, general changes or breaking changes.

What both these lack is a marker to show which area has been changed. Given such a thing (eg a boost which library the change applies to) would be just as good as a customised changelog per developer, significantly easier to create and maintain, and would satisfy the curiosity of those dev who do read changelogs.

Oh, and some devs will not be using a particular API because of a lack of feature or bug.. how will they be informed when the API is enhanced or fixed to make it suitable for them to want to start using it if they can't see it in the changelog?!

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.