The basics

1. Minimize breaking changes when practical, but prioritize them over API sprawl. When facing a breaking change, consider whether a backwards-compatible approach would significantly complicate the API or create maintenance burden through endpoint proliferation.

2. If you are unable to make your change backwards compatible, be prepared to explain to other teams WHY you must make a breaking change, and provide the justification when you announce your intention to make the change. Be prepared to interact with other teams and answer their questions about the work you are creating for them.

3. Announce your intention to make the breaking change as soon as possible.

4. FOLIO’s definition of breaking changes can be found here: https://github.com/folio-org/rfcs/blob/master/text/0003-folio-breaking-changes.md

Announcing breaking changes

• Create a ticket for the breaking change and tickets for any known dependent modules.

• Post the information about the breaking change to the following channels and include the justification for the breaking change and answer questions as they arise

  • #folio-development

  • #folio-sys-ops

  • #folio-breaking-changes

• Once the ticket for the breaking change is merged the interdependent tickets are notified so the devs responsible for them can do the necessary changes.