Experimental Physics and
Industrial Control System

<[email protected]> · Tue, 29 May 2012 09:05:52 +0000

I'm going to quote the entirety of Dirk's message.

From: [email protected] [mailto:tech-talk-
> I like backward compatibility. This allows to take care only of the
> changes that I really need.
> 
> When upgrading to a new version of a certain (3rd party) driver, I
> usually spend some time on tracking the changes. I do that because of
> bad experience. Drivers change behavior, change APIs and so on. Recent
> example: base 3.14.12 broke the ca gateway because of an API change.
> Other example: the OMS VME58 driver once dropped one (unused) argument
> from it's configuration function. Everybody had to change their startup
> scripts. These changes usually induce a lot of work in addition to
> simply downloading the new code and compiling it.
> 
> When there are many cross-dependencies like in areaDetector, things are
> getting worse. Suddenly I have to track changes in 5 or more other
> modules (and maybe they require further updates and so on). This costs
> me a lot of my time. This is why I would appreciate to have more
> flexibility in mixing versions and to be able to upgrade only that what
> I really need and want to upgrade.
> 
> By the way, I also appreciate binary compatibility. Up to EPICS base
> 3.14.8 (maybe even up to 3.14.11), large parts of base were binary
> compatible. I could for example upgrade all extensions just by
> upgrading base. 3.14.12 broke this mechanism.
> 
> Some guidelines would help to to keep binary compatibility:
> 
> Do not remove API functions or change their arguments. Do not change
> the meaning (e.g. units) of an argument. Better write additional API
> functions if necessary.
> 
> Do not remove or reorder fields of interface structures. Do not insert
> fields in the middle. Add them at the end. Keep supporting old fields.
> 
> Do not remove shared libraries.
> 
> Also put version macros into your header files if they are used by
> other code. This allows other code to deal with different interfaces.
> 
> It *is* possible to improve software without breaking all existing
> interfaces.
> 
> Or do it like the Linux kernel developers do: Someone who changes an
> interface is responsible for fixing (and testing ?) all drivers that
> use that interface. This of course only works when all drivers are in one
> common repository.
> 
> At the moment I am very hesitant when it comes to upgrades of third
> party drivers because of all the unknown side effects.

What can I say, except: yes, yes, again yes!

Please folks, please pay attention to backwards compatibility.  Mostly it requires just a little attention to the details that Dirk mentions.

One more detail regarding enumerations: when adding values to an enumeration, add them to the *end*, not in the middle, and please *don't* just delete values from the middle of an enumeration list -- if you really want to delete a value then assign explicit (and backwards compatible) values to everything before you delete the offending value.

To be honest I'm speechless to express the frustration I've found in trying to deal with gratuitous changes to interfaces.  *Sometimes* you need to break things.  Sometimes...  Most of the time it's just either inattention or being completely oblivious to the fact that backwards compatibility is a good thing.

So, in summary: please do what Dirk says here!

-- 
This e-mail and any attachments may contain confidential, copyright and or privileged material, and are for the use of the intended addressee only. If you are not the intended addressee or an authorised recipient of the addressee please notify us of receipt by returning the e-mail and do not use, copy, retain, distribute or disclose the information in or attached to the e-mail.
Any opinions expressed within this e-mail are those of the individual and not necessarily of Diamond Light Source Ltd. 
Diamond Light Source Ltd. cannot guarantee that this e-mail or any attachments are free from viruses and we cannot accept liability for any damage which you may sustain as a result of software viruses which may be transmitted in or with the message.
Diamond Light Source Limited (company no. 4375679). Registered in England and Wales with its registered office at Diamond House, Harwell Science and Innovation Campus, Didcot, Oxfordshire, OX11 0DE, United Kingdom

Experimental Physics and Industrial Control System

Experimental Physics and
Industrial Control System