[macios-devel] Breaking Changes

[Sebastien Pouliot]

Bonsoir!

One of the tricky aspects of working, and now contributing, to Xamarin.[iOS
| Mac] is dealing with breaking changes.



Whenever a public/visible API is modified the consumers of the assemblies
are at risk of becoming unusable. That's a big problem when working with
assemblies binaries (e.g. 3rd party components) because re-compiling them
is not an option.

This is why we strive to never [0] introduce breaking changes in our stable
releases and, as much as possible, in any beta or alpha releases.

Still that does not solve the issue of the broken API itself. To do this we
need to take a few steps:

1. *The workaround*: Add an [Obsolete] attribute to the "broken" API,
explaining why and the best way/API to replace any code using it. Never
remove or modify the "broken" but visible API;

2. *The short term fix*: Add the new, fixed, API;

3. *The long term fix*: At some point we might have to break compatibility
(e.g. classic vs unified) or have a clean up opportunity (e.g. new
platforms like watchOS and tvOS). At those stage we can "remove" the
workaround/broken API.

To allow this we use defines for profiles, e.g.

   - XAMCORE_2_0 was used unified (versus classic);
   - XAMCORE_3_0 is for tvOS / watchOS (but not for iOS or Mac); and
   - XAMCORE_4_0 for a future (not shipped) break - *that might never
   happen*;

If you have looked into our code then you likely have see those define
quite frequently.

*Now don't worry if any of this sounds confusing.* Everyone working on
XI/XM always to double check each others to avoid those breaking changes
from sneaking in :-)

So if you see anything broken report it and/or do a pull request (PR) while
we'll continue watching for them (and your help for this will be welcome).
We will soon have a PR to show how it's "done" to solve PR #19 [1] without
breaking changes.

Thanks!
Sebastien

[0] like any rule there's a (very) few cases where it cannot be applied.
Whenever in doubt don't hesitate to ask

[1] https://github.com/xamarin/xamarin-macios/pull/19
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ximian.com/pipermail/macios-devel/attachments/20160502/cbceb108/attachment.html>