Breaking changes


When building software, it is possible to optimize for any two of these three attributes:

  1. Ship early and update often  (to get feedback from real customers)
  2. Have the flexibility to fix mistakes  (so if you build something but later realize it would be better done a different way, you are able to change it)
  3. Avoid breaking changes  (it quickly gets annoying for customers if every time they update to a new version their code no longer compiles, or if things they considered finished are now done a different way)

Most projects I worked on in the past focused on #2 and #3 at the expense of #1.  In order to fix mistakes without breaking customers, development took place in private, and new versions were only released once the team believed at least most of the mistakes were gone.

We are trying something different with Win2D, optimizing for #1 and #2 at the expense of #3.  We release new code every two weeks, warts and all, and fix things later if time or feedback shows us ways to make it better.  One of the nice things about being open source with side-by-side versioning is that we can for instance rename a method, yet existing apps will only be affected if their developers choose to upgrade to a newer version of Win2D, so there is no risk of the rename breaking apps that have already been released.

I’m mostly very happy with this approach, but I sometimes worry our breaking changes might be too annoying.  I would love to hear your feedback on this.  If you are using Win2D, do you update every time we release new code?  How straightforward are you finding these updates?


Comments (8)

  1. Greg says:

    I have not been using Win2D but would like to (don't seem to have time right now) so option 2 is good for me…

  2. Omari_O says:

    In the long term I would prefer to have thoroughly thought and tested API.

    So untill version 1.0 you are free to break compatibility as often as it needed. But after that pay more attention to #3.

  3. Hans says:

    I update (almost) every time, and have had to modify my code a couple of times because of breaking changes.

    I don't mind that, it is for a good cause (Win2D getting even better).

    What really helps is that you clearly describe any breaking changes, explain why it was changed, and perhaps provide a code sample how to modify existing code. The articles about async resource loading were great! They explained (in depth) why certain choices were made, and they provided sample code how to correctly use this feature.

    So keep up the good work, break whatever you want to break, and please educate us on the how and why. 😉

  4. KooKiz says:

    I agree with Omari_O. The breaking changes will become a bother only when the API becomes mature enough to be included in major commercial apps. Until then, it's good to fill the immediate needs with a quick release cycle.

  5. leandro says:

    我很高兴测试新的api

  6. Johnny Westlake says:

    Honestly, I don't mind. I'd very much say avoid hampering the design of the library just because you want to avoid breaking changes. If there are better and more logical ways of doing things, break it – especially at this stage in the life cycle.

    And as you say, if developers are having their needs met by their current version, and a newer version includes breaking changes to their code, they're under no obligation to update. Plus, more frequent updates can lead to more frequent feedback, useful at an early-ish stage like this.

  7. Omari_O says:

    Good way to develop API is to try it in a real app of fair complexity.

    Like Hilo – example app demonstrating new API in Win 7 and Win 8.

    msdn.microsoft.com/…/ff708696.aspx

    msdn.microsoft.com/…/jj160316.aspx

  8. Grokys says:

    Go ahead and break as often as you like!

Skip to main content