- Start Date: 2022-10-21
- RFC PR:
- FOLIO Issue:
This RFC's purpose is to deliver to developers and other effected groups general guidlines for determining if a changes within Folio is either a breaking or non-breaking change.
- To help different Folio implementors know with every release what significant changes have been added.
- An extensive guide of those significant changes grouping them into breaking and non-breaking changes.
This RFC aims to outline possible changes made in FOLIO at the implementation or interface level as breaking and non-breaking changes. Because both implementations and interfaces are versioned independently of each other, this document will address breaking and non breaking changes at both the implementation and interface levels.
Additional distinctions must be made between backend vs. UI changes, for implementation versioning, and API vs Data Model changes at the interface level. Behavioral changes, though signigicant and worth addressings, are outside the scope of this RFC.
Throughout this RFC we will be discussing changes in terms of the following three categories
- What is a breaking change at the implementation level?
- What is a breaking change at the interface level?
- We will not address what constitutes as a breaking change in the behavioral level, though this will be an important topic to broach in the future.
- Types of changes which can be considered breaking are:
Changes Examples Infrastructural change A implementation requires Kafka, Postgres, etc. Non-infrastructural changes implementations need Java v17, Node v16, etc. Configurational changes Change to environmental variables, etc.
-
In UI Implementations:
Use Cases Breaking Change Non-Breaking New minimum version change of an Okapi interface X New interface version change of an Okapi interface X New peer dependency addition X Version Change of a peer dependency X Public Route addition X Public Route removal X Addition of a new direct dependency X Addition of a new development dependency X Changing version of an existing direct dependency X Changing version of existing development dependency X Addition of new version of existing OKAPI interface X -
In Backend Implementations :
Use Cases Breaking Change Non-Breaking Dropping support for interface version X Removing any interface X Changing minor version of an interface X New operational requirement X New interface addition w.r.t. Okapi X Major change within an interface X implementation stops providing an interface X Runtime environment changes X Adding a trailing '0' to an interface version X Bumping the minor version of an interface X Addition of new interface X Adding new code optimisations X Adding new functionalities X
-
Changes in the API :
Use Case Breaking Change Non-Breaking Removing an endpoint X Changing the response content type X Adding or removing HTTP status code X Adding a new endpoint X -
Changes to the Data model:
Use Case Breaking Change Non-Breaking Removing a required field X Adding a new optional field X Removing an optional field X
- Interfaces only represent the communication protocol, i.e. the shape of a request/response to/from a given endpoint. Behavior changes are part of a implementation’s version, e.g. if circulation adds additional actions when receiving a request at /checkout such as sending notifications or checking fees/fines but continues to send the same response, the interface version will not change.
A detailed RFC and ADR is made with guide to recognise and communicate probable breaking changes to the effected developers, etc, but after all these efforts, the guide is used by no-one.
[TO DO]: Complete this section
- How to provide the guidance for versioning Behavioral changes?
- What kind of change would result from the dropping of a minor/patch version of a runtime dependency? (Note that a dev doesn’t get to set the java version of the platform because container config happens independent of implementation development)
- How to provide a clear guidance as to how the proposal should be implemented?