Add extracted tools: CitrineOS, OpenOCPP, ShapeShifter
- 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
This commit is contained in:
Eric F
@@ -0,0 +1,251 @@
|
||||
.. _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.
|
||||
Reference in New Issue
Block a user