d398a6ced2
- CitrineOS core extracted (CSMS OCPP 2.0.1) - OpenOCPP extracted (firmware OCPP 1.6J/2.0.1) - ShapeShifter library installed (pip install -e) - ShapeShifter specification extracted - EVerest extracted TODO updated with progress
252 lines
8.4 KiB
ReStructuredText
252 lines
8.4 KiB
ReStructuredText
.. _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.
|