.. _project-breaking-changes:

############################
Breaking Changes Definition
############################

This document defines what constitutes a breaking change versus a non-breaking change for the components of the
:ref:`EVerest public API <project-release-and-versioning-public-api>`.
Understanding these definitions is critical for both maintainers and integrators.

********
Overview
********

General Principle
=================

A change is considered **breaking** if it requires integrators to modify their code, configuration, or deployment
to maintain existing functionality. A change is **non-breaking** if existing integrations continue to work
without modification when upgrading to a new version of EVerest.

Scope
=====

This document covers breaking change definitions for all components of the :ref:`EVerest public API <project-release-and-versioning-public-api>`.

This includes:

- :ref:`AsyncAPI specifications <exp-breaking-changes-asyncapi>`
- :ref:`Configuration files and storage contracts <exp-breaking-changes-configuration>`

.. _exp-breaking-changes-asyncapi:

****************
AsyncAPI Changes
****************

Breaking Changes
================

The following changes to :doc:`AsyncAPI specifications </reference/api/autogenerated_api_index>` are considered breaking:

**Channels:**

- Changing a channel address (e.g., ``e2m/session_event`` → ``e2m/session_events``)
- Removing a channel that external clients use

**Operations:**

- Removing an operation (send/receive) that external clients use
- Changing an operation's action (e.g., ``send`` → ``receive``)
- Changing which channel an operation references

**Messages:**

- Removing a field from a message payload that clients may read
- Changing the data type of an existing field (e.g., ``number`` → ``string``)
- Making an optional field required in messages that clients send
- Changing field semantics that affect expected behavior (e.g., units, value ranges)
- Adding ``required`` constraints to previously unconstrained fields
- Changing ``enum`` values or removing enum options

**Behavioral Changes:**

- Changing error handling behavior (e.g., silently ignoring invalid values → raising errors)
- Changing validation strictness (e.g., accepting malformed data → rejecting it)
- Changing message ordering or timing guarantees that clients depend on

**Protocol:**

- Removing support for a protocol version that clients use
- Changing server host, pathname, or protocol bindings

Examples
--------

**Breaking**: Renaming channel ``e2m/session_event`` → ``e2m/session_events`` breaks all subscribers.

**Breaking**: Changing ``EVInfo.soc`` from ``number`` to ``string`` requires client parser updates.

**Breaking**: Making ``StopTransactionRequest.id_tag`` required breaks clients that omit it.

**Breaking**: Requiring ``m2e/disable_charging`` to be called before ``m2e/unlock_connector`` breaks clients
that previously called unlock directly.

**Breaking**: Previously accepting invalid ``connector_id: -1`` and ignoring it, now rejecting with error
breaks clients sending invalid data.

Non-Breaking Changes
====================

The following changes are generally non-breaking:

**Channels:**

- Adding a new channel with a new address

**Operations:**

- Adding a new operation on a new or existing channel

**Messages:**

- Adding a new message type (clients can ignore unknown messages)
- Adding optional fields to existing message payloads
- Making a required field optional in messages that EVerest sends
- Adding new enum values
- Expanding valid value ranges (e.g., ``minimum: 0`` → ``minimum: -10``)

**Documentation:**

- Clarifying documentation without changing behavior
- Adding examples or improving descriptions

**Protocol:**

- Adding a new protocol version while maintaining existing versions

Examples
--------

**Non-breaking**: Adding new channel ``e2m/detailed_session_event`` alongside existing ``e2m/session_event``.

**Non-breaking**: Adding optional field ``battery_temperature`` to ``EVInfo`` (clients can ignore).

**Non-breaking**: Adding ``"FastCharging"`` to ``SessionEventEnum`` (if clients handle unknown values).

.. _exp-breaking-changes-configuration:

***********************************
Configuration and Storage Contracts
***********************************

Configuration changes directly affect deployment processes and runtime behavior. The following principles apply 
to EVerest YAML/SQLite configurations and OCPP JSON/SQLite configurations.

Some SQLite implementations in EVerest support automatic schema migrations to minimize breaking changes. However, 
schema changes requiring manual intervention or altering existing data formats are considered breaking.

Breaking Changes
================

**Configuration Options:**

- Removing a configuration option that deployments use
- Renaming a configuration option (e.g., ``connector_type`` → ``connector_standard``)
- Changing the type of a value (e.g., ``boolean`` → ``string``)
- Making an optional option required without a sensible default
- Changing the meaning or behavior of an option (e.g., units, semantics)
- Changing default values that affect runtime behavior
- Narrowing acceptable value ranges (e.g., 0-100 → 1-100)

**File Formats:**

- Changing YAML/JSON schema in incompatible ways (e.g., structure changes)
- Changing file locations or naming conventions that deployments rely on

**Database Schemas:**

- Removing or renaming tables/columns that are actively used
- Changing column types without migration support
- Adding ``NOT NULL`` constraints to existing columns without defaults
- Changing primary keys or foreign key relationships

Examples
--------

**Breaking**: Removing ``EvseManager.connector_id`` breaks all configs that set it.

**Breaking**: Changing ``ac_hlc_enabled`` from ``boolean`` to ``enum`` (``"always"|"never"``) breaks existing configs.

**Breaking**: OCPP: Renaming table ``VARIABLE_ATTRIBUTE`` → ``VARIABLE_ATTRIBUTES`` without migration.

Non-Breaking Changes
====================

**Configuration Options:**

- Adding a new optional option with a documented default
- Making a required option optional with a backward-compatible default
- Expanding acceptable value ranges if existing implementations don't reject the new values (e.g., 1-100 → 0-100)
- Adding new enum values while preserving existing ones
- Improving documentation or examples

**Database Schemas:**

- Adding a new table for new functionality
- Adding a new column with a default value and automatic migration
- Adding optional indexes for performance
- Relaxing ``NOT NULL`` constraints

Examples
--------

**Non-breaking**: Adding ``EvseManager.enable_load_balancing`` with default ``false``.

**Non-breaking**: Accepting ``connector_type: "CCS1"`` alongside existing ``"CCS"``.

**Non-breaking**: OCPP: Adding ``VARIABLE_ATTRIBUTE.last_updated`` column with default ``NULL`` and migration script.

********************
Practical Guidelines
********************

When in Doubt
=============

If you are unsure whether a change is breaking:

- Assume it is breaking and treat it conservatively
- Consult with the maintainers and/or TSC for significant changes
- Gather community feedback during testing periods
- Test with real-world deployments when possible

Review Checklist
================

Before merging changes, ask yourself these questions:

Configuration Compatibility
---------------------------

1. Can existing EVerest and OCPP configuration files still be loaded?
2. Will existing configuration values still have the same effect?
3. Are we changing any default values?
4. Are we removing or renaming any configuration options?

Integration Compatibility
--------------------------

5. Will existing external API clients continue to work?
6. Are we removing or changing any public API methods/messages?
7. Are we changing any API semantics, expected behaviors, or side effects?
8. Will existing stored data still be readable?

Behavioral Compatibility
-------------------------

9. Are we changing behavior that deployments rely on?
10. Are we removing functionality that might be in use?
11. Are bug fixes potentially breaking workarounds?
12. Will performance characteristics change significantly?

********************
Additional Resources
********************

For more information on EVerest's release and versioning strategy, see :ref:`project-release-and-versioning`.

For questions about breaking changes or to report potential compatibility issues, please contact the EVerest
maintainers or raise an issue in the GitHub repository.
