Managing Change

• Avoid introducing breaking changes. Wherever possible, retain old overloads/names for one extra major version.
• Document breaking changes in the release notes, including upgrade instructions.

• Will customer code be affected? A “customer” in this case is anyone who consumes your code: both internal and external developers.
• Is all of the code that depends on code integrated at least daily in order to catch any usages you might have forgotten?
• Is the area you are changing covered by automated tests?
• Just how important is the change?
• Can you make the change in a non-destructive manner by introducing an optional parameter or an overload instead?
• Are you willing to introduce a compile error into customer code?

1. Mark the old version of the feature as obsolete.
2. Create the new feature with a different name so that it does not collide with the existing feature.
3. Add an issue to complete the next stage of refactoring in the next release.
4. Make and distribute a point release.
5. In the next release, remove the obsolete feature and all handling for it.
6. Rename the new feature to the desired name but retain a copy with the temporary name as well, marking it as obsolete.
7. Update the issue to indicate that it should be completed in the next release.
8. Make and distribute a point release.
9. In the next release, remove the obsolete version with the temporary name and the refactoring is complete.