​Breaking Changes

How to break an API? It depends . . .

Change in software ecosystems with interdependent but independently developed packages can be disruptive. Breaking changes (e.g., removing, renaming, changing contracts) can ripple through the entire ecosystem, causing rework for many package maintainers and users. Developers tend to avoid breaking changes when they can, but they are still common in practice.

While performing the change can be easy, a change can cause huge costs in rework and interruptions for users of the package. As each participant has their own goals, priorities, habits, and rhythms, there is often (implicit) negotiation about changes regarding when, how, and who. Different developers and different communities have different attitudes toward who should pay the costs of a change and when.

We are developing theory about how change is managed and its relationship to the health of a software ecosystem. Costs of managing change should ideally be as low as possible, be distributed in ways that are perceived as fair and do not drive away key participants. Tools, practices, and policies can shift costs from participants in one role to participants in other roles, so they become a primary mechanism to move an ecosystem toward health.

In this project, just getting under way, we are performing qualitative and quantitative research to inform theory development, to investigate the implications of our theory empirically, and to develop a collection of ecosystem design patterns that can help companies, foundations, and other ecosystem stewards ensure make vibrancy-enhancing decisions.

Some of our preliminary results:

Maintainers can reduce rework costs for users by investing extra work when making the change:

  • Documenting or signaling what changed (e.g., semantic versioning) and announcing changes (e.g., twitter, conferences) makes it easier to identify when rework might be needed.
  • Providing a migration guide reduce rework costs.
  • Reaching out to affected developers and helping them migrate (e.g., sending pull request) reduces their rework costs.
  • Involving users in change decisions can lead to those changes being less disruptive.

Maintainers can invest extra work to reduce interruptions to users, delay their rework costs, and help them plan ahead:

  • Providing parallel maintenance releases and backporting important changes (e.g., security patches) so as not to force users to update before they are ready.
  • Maintaining old interfaces, possibly marked as deprecated, allows users to delay rework.
  • Release planning, such as yearly coordinated releases, helps users plan ahead; delaying changes and releasing multiple breaking changes together reduces interruptions.

Third parties or volunteers can take on some of change costs by vetting changes or mediating between parties. Acting as gatekeepers, they may review changes for quality and security or curate a selection of recommended packages. Some may choose to release a whole collection of packages at once in regular intervals.

Users can reduce their own exposure to change and manage their effort in monitoring change:

  • Avoiding dependencies by instead recreating or copying functionality reduces exposure to external change, but risks missing important patches.
  • Carefully selecting stable or reputable packages reduces change-related surprises.
  • Using an abstraction layer to encapsulate dependencies can reduce the scope of future rework.
  • Influencing development of used packages can discourage incompatible changes.
  • Continuous integration and other automated tools producing notifications on breaking changes can help to react quickly to change. By distinguishing breaking from nonbreaking changes, such techniques can steer focus toward important changes and can avoid amounting a backlog of changes. Learn More About This Project

Learn More About This Project

Project Publications

C. Bogart, C. Kästner, J. Herbsleb, and F. Thung. How to Break an API: Cost Negotiation and Community Values in Three Software Ecosystems. In Proceedings of the ACM SIGSOFT Symposium on the Foundations of Software Engineering (FSE), New York, NY: ACM Press, November 2016.

  • Related Research ​Hacking a Community Read More
  • Related Research ​Livehoods Project Read More