* they can either strictly keep [[BackwardCompatibility]] - [[I|my]] favorite, of course

* they can either strictly keep [[BackwardCompatibility]] - [[I|my]] favorite, of course

* or at least use [[deprecation]]s as a notice to give downstream projects a chance to adopt to the [[API]] changes.

* or at least use [[deprecation]]s as a notice to give downstream projects a chance to adopt to the [[API]] changes.

Both approaches satisfy the major goal of avoiding complete [[Big Bang]] rewrites and provide some interval when downstream code works with multiple [[version]]s.

Both approaches satisfy the major goal of avoiding complete [[Big Bang]] rewrites and provide some interval when downstream code works with multiple [[version]]s. In any case, if you have to modify your tests, there is something fishy with your change!

== Conclusion ==

== Conclusion ==

As a result of that [[API]] maintainers need to invest in defining and following [[API]]-like [[lifecycle]] of their framework:

As a result of that [[API]] maintainers need to invest in defining and following [[API]]-like [[lifecycle]] of their framework:

* they can stick to strict keeping of [[BackwardCompatibility]] - [[I|my]] favorite, of course

* they can either strictly keep [[BackwardCompatibility]] - [[I|my]] favorite, of course

* or at least use [[deprecation]]s as a notice to give downstream projects a chance to adopt to the [[API]] changes.

* or at least use [[deprecation]]s as a notice to give downstream projects a chance to adopt to the [[API]] changes.

Both approaches satisfy the major goal of avoiding complete [[Big Bang]] rewrites and provide some interval when downstream code works with multiple [[version]]s.

Both approaches satisfy the major goal of avoiding complete [[Big Bang]] rewrites and provide some interval when downstream code works with multiple [[version]]s.

== U Can't Change It Whole! ==

== U Can't Change It Whole! ==

Traditional in-house development scheme suggests [[refactoring]]s to clean up the code and improve its quality. In such model it is fine to do incompatible changes in the code base. If they break some tests, one fixes the tests as well. Ones your [[ContinuousIntegration]] is green again, you can integrate.

Traditional in-house development scheme suggests [[refactoring]]s to clean up the code and improve its quality. In such model it is fine to do incompatible changes in the code base. If they break some tests, one fixes the tests as well. Once your [[ContinuousIntegration]] is green again, you can integrate.

There is however a hidden assumption: one needs an ''instant access to all the code'' and perform the whole change at once. This is far from reality when it comes to [[APIDesign]] and maintaining frameworks. [[API]]s are like [[Star]]s and building them feels like building Universe, not a house. You never know who's watching (e.g. using) your [[API]] and you can't fix all the usages at once.

There is however a hidden assumption: one needs an ''instant access to all the code'' and perform the whole change at once. This is far from reality when it comes to [[APIDesign]] and maintaining frameworks. [[API]]s are like [[Star]]s and building them feels like building Universe, not a house. You never know who's watching (e.g. using) your [[API]] and you can't fix all the usages at once.

There is however a hidden assumption: one needs an ''instant access to all the code'' and perform the whole change at once. This is far from reality when it comes to [[APIDesign]] and maintaining frameworks. [[API]]s are like [[Star]]s and building them feels like building Universe, not a house. You never know who's watching (e.g. using) your [[API]] and you can't fix all the usages at once.

There is however a hidden assumption: one needs an ''instant access to all the code'' and perform the whole change at once. This is far from reality when it comes to [[APIDesign]] and maintaining frameworks. [[API]]s are like [[Star]]s and building them feels like building Universe, not a house. You never know who's watching (e.g. using) your [[API]] and you can't fix all the usages at once.

It makes no sense to claim: ''Everything is OK, my [[ContinuousIntegration]] server is green''! It may be, when you had to fix your tests. If your [[API]] is any popular, there are tons of code similar to your tests out there and there is nobody to fix them as part of your [[refactoring]]. Better to learn and investing in keeping a bit of [[BackwardCompatibility]].

It makes no sense to claim: ''Everything is OK, my [[ContinuousIntegration]] server is green''! It may be, when you had to fix your tests. If your [[API]] is any popular, there are tons of code similar to your tests out there and there is nobody to fix them as part of your [[refactoring]]. Better to learn and invest in keeping a bit of [[BackwardCompatibility]].

As a result of that [[API]] maintainers need to invest in defining and following [[API]]-like [[lifecycle]] of their framework:

As a result of that [[API]] maintainers need to invest in defining and following [[API]]-like [[lifecycle]] of their framework:

== Conclusion ==

== Conclusion ==

Having [[ContinuousIntegration]] is a must for any project (including ones that provide an [[API]]). However in contrast to building final applications one cannot fit the whole code into the [[ContinuousIntegration]] check. As a result of that one needs to apply also other techniques when judging correctness of a change. Keeping [[BackwardCompatibility]] is a useful initial step that greatly pays off in a long run.

Having [[ContinuousIntegration]] is a must for any project (including ones that provide an [[API]]). However in contrast to building final applications one cannot fit the whole code into the [[ContinuousIntegration]] check. As a result of that one needs to apply also other techniques when judging correctness of a change. Keeping [[BackwardCompatibility]] (at least temporarily) is a useful initial step that greatly pays off in a long run.

We have just found another [[paradox]] of [[APIDesign]]: relying only on [[ContinuousIntegration]] is bad!

We have just found another [[paradox]] of [[APIDesign]]: relying only on [[ContinuousIntegration]] is bad!

[[Category:APIDesignPatterns:Anti]]

[[Category:APIDesignPatterns:Anti]]

There is however a hidden assumption: one needs an ''instant access to all the code'' and perform the whole change at once. This is far from reality when it comes to [[APIDesign]] and maintaining frameworks. [[API]]s are like [[Star]]s and building them feels like building Universe, not a house. You never know who's watching (e.g. using) your [[API]] and you can't fix all the usages at once.

There is however a hidden assumption: one needs an ''instant access to all the code'' and perform the whole change at once. This is far from reality when it comes to [[APIDesign]] and maintaining frameworks. [[API]]s are like [[Star]]s and building them feels like building Universe, not a house. You never know who's watching (e.g. using) your [[API]] and you can't fix all the usages at once.

As a result of that [[API]] maintainers need to invest in defining and following proper [[lifecycle]] of their [[API]]. On one side, there is a strict request to keep [[BackwardCompatibility]], on the other side there is a [[deprecation]] (as a notice) followed by some period of time to give downstream projects a chance to adopt to the [[API]] change. Both approaches satisfy the major goal and are certainly better than [[Big Bang]] rewrites.

As a result of that [[API]] maintainers need to invest in defining and following [[API]]-like [[lifecycle]] of their framework:

 

* they can stick to strict keeping of [[BackwardCompatibility]] - [[I|my]] favorite, of course

It makes no sense to claim: ''Everything is OK, my [[ContinuousIntegration]] server is green''! when you had to fix your tests. If your [[API]] is any good, there are tons of code similar to your tests out there and there is nobody to fix them as part of your [[refactoring]]. Better to learn and investing in keeping a bit of [[BackwardCompatibility]].

* or at least use [[deprecation]]s as a notice to give downstream projects a chance to adopt to the [[API]] changes.

Both approaches satisfy the major goal of avoiding complete [[Big Bang]] rewrites and provide some interval when downstream code works with multiple [[version]]s.

== Conclusion ==

== Conclusion ==

Traditional in-house development scheme suggests [[refactoring]]s to clean up the code and improve its quality. In such model it is fine to do incompatible changes in the code base. If they break some tests, one fixes the tests as well. Ones your [[ContinuousIntegration]] is green again, you can integrate.

Traditional in-house development scheme suggests [[refactoring]]s to clean up the code and improve its quality. In such model it is fine to do incompatible changes in the code base. If they break some tests, one fixes the tests as well. Ones your [[ContinuousIntegration]] is green again, you can integrate.

There is however a hidden assumption: one needs an instant access to all the code and perform the whole change at once. This is far from reality when it comes to [[APIDesign]] and maintaining frameworks. [[API]]s are like [[Star]]s and building them feels like building Universe, not a house. You never know who's watching (e.g. using) your [[API]] and you can't fix all the usages at once.

There is however a hidden assumption: one needs an ''instant access to all the code'' and perform the whole change at once. This is far from reality when it comes to [[APIDesign]] and maintaining frameworks. [[API]]s are like [[Star]]s and building them feels like building Universe, not a house. You never know who's watching (e.g. using) your [[API]] and you can't fix all the usages at once.

As a result of that [[API]] maintainers need to invest in defining and following proper [[lifecycle]] of their [[API]]. On one side, there is a strict request to keep [[BackwardCompatibility]], on the other side there is a [[deprecation]] (as a notice) followed by some period of time to give downstream projects a chance to adopt to the [[API]] change. Both approaches satisfy the major goal and are certainly better than [[Big Bang]] rewrites.

As a result of that [[API]] maintainers need to invest in defining and following proper [[lifecycle]] of their [[API]]. On one side, there is a strict request to keep [[BackwardCompatibility]], on the other side there is a [[deprecation]] (as a notice) followed by some period of time to give downstream projects a chance to adopt to the [[API]] change. Both approaches satisfy the major goal and are certainly better than [[Big Bang]] rewrites.

== What's the Goal? ==

== What's the Goal? ==

The goal is to make sure that people can write applications, libraries and plugins in a way that continues to work with multiple [[version]]s of your [[API]]. Nobody wants to publish update as soon as you provide new version of the [[API]]. Things shall just continue to work. This is called [[BackwardCompatibility]].

The goal is to make sure that people can write applications, libraries and plugins in a way that continues to work with multiple [[version]]s of your [[API]]. Nobody wants to publish updates as soon as you provide new version of your [[API]]. Downstream projects shall just continue to work. This is called [[BackwardCompatibility]].

[[NetBeans]] IDE supported plugins since 2000 and the most important feature people asked for was ability to write a plugin and make it work with last few versions of [[NetBeans]] simultaneously. Their core business wasn't to write plugins, so they wanted to minimize the time spent doing that. The last thing they wanted was to watch us to release new version of [[NetBeans]] and at that time immediately re-publish an update of their plugin suitable to run with that version.

[[NetBeans]] IDE supported plugins since 2000 and the most important feature people asked for was ability to write a plugin and make it work with last few versions of [[NetBeans]] simultaneously. Their core business wasn't to write plugins, so they wanted to minimize the time spent doing that. The last thing they wanted was to watch us to release new version of [[NetBeans]] and at that time immediately re-publish an update of their plugin suitable to run with that version.

In such case choose to provide [[AlternativeBehavior]]s! There are few [[AlternativeBehavior|ways to do it]] applicable to any [[language]], but the best is when the language or its underlaying [[NetBeans Runtime Container|runtime container]] provides some support to do it smoothly.

In such case choose to provide [[AlternativeBehavior]]s! There are few [[AlternativeBehavior|ways to do it]] applicable to any [[language]], but the best is when the language or its underlaying [[NetBeans Runtime Container|runtime container]] provides some support to do it smoothly.

For example [[XML]] does that by encoding its own version in the document header and than it is clear which parser to use to provide the right [[AlternativeBehavior]]. On the other hand [[Python]] is famous for not identifying its [[language]] version and changing its syntax in a slightly incompatible way that started years of the [[Python]] ''2.x'' vs. ''3.0'' battle.

For example [[XML]] does that by encoding its own version in the document header and than it is clear which parser to use to provide the right [[AlternativeBehavior|alternative interpretation]]. On the other hand [[Python]] is famous for not identifying its [[language]] version and changing its syntax in a slightly incompatible way that started years of the [[Python]] ''2.x'' vs. ''3.0'' battle.

== What's the Goal? ==

== What's the Goal? ==

As far as runtime compatibility goes, it is easy to say: ''keep existing behavior''. But what if such behavior is buggy? Well, sometimes even buggy (from one perspective) behavior can be useful (see the [[Arithmetica]] example) and should be preserved. What can you do when you really need to change it?

As far as runtime compatibility goes, it is easy to say: ''keep existing behavior''. But what if such behavior is buggy? Well, sometimes even buggy (from one perspective) behavior can be useful (see the [[Arithmetica]] example) and should be preserved. What can you do when you really need to change it?

In such case choose to provide [[AlternativeBehavior]]s! There are few [[AlternativeBehavior|ways to do it]] applicable to any [[language]], but the best is when the language or its underlaying [[NetBeans Runtime Container|runtime container]] provides some support to it.

In such case choose to provide [[AlternativeBehavior]]s! There are few [[AlternativeBehavior|ways to do it]] applicable to any [[language]], but the best is when the language or its underlaying [[NetBeans Runtime Container|runtime container]] provides some support to do it smoothly.

For example [[XML]] does that by encoding its own version in the document header and than it is clear which parser to use to provide the right [[AlternativeBehavior]]. On the other hand [[Python]] is famous for not identifying its [[language]] version and changing its syntax in a slightly incompatible way that started years of the [[Python]] ''2.x'' vs. ''3.0'' battle.

For example [[XML]] does that by encoding its own version in the document header and than it is clear which parser to use to provide the right [[AlternativeBehavior]]. On the other hand [[Python]] is famous for not identifying its [[language]] version and changing its syntax in a slightly incompatible way that started years of the [[Python]] ''2.x'' vs. ''3.0'' battle.