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.
|
||||
@@ -0,0 +1,154 @@
|
||||
.. _project-release-and-versioning:
|
||||
|
||||
##################################
|
||||
Releases and Versioning of EVerest
|
||||
##################################
|
||||
|
||||
This document describes EVerest's release strategy, versioning scheme, and stability guarantees for the project and its components.
|
||||
|
||||
Release Cadence
|
||||
===============
|
||||
|
||||
EVerest follows a time-based release strategy with stable releases every 6 months. Each stable release receives community maintenance
|
||||
and follows explicit API stability guarantees. Each stable release undergoes a coordinated testing period before being published to
|
||||
ensure quality and stability.
|
||||
|
||||
.. note::
|
||||
|
||||
Monthly snapshot releases have been discontinued in favor of this stable release approach since 2026.
|
||||
|
||||
Versioning
|
||||
==========
|
||||
|
||||
Versioning Format
|
||||
-----------------
|
||||
|
||||
EVerest uses calendar-based versioning (CalVer) in the format:
|
||||
|
||||
.. code-block::
|
||||
|
||||
yyyy.mm.x
|
||||
|
||||
Where:
|
||||
|
||||
- ``yyyy`` - Four-digit year of the release
|
||||
- ``mm`` - Two-digit month of the release (01-12)
|
||||
- ``x`` - Incremental patch number within the stable release line, starting at 0
|
||||
|
||||
Releases are made available through Github Releases and tags in the EVerest repository:
|
||||
|
||||
- `EVerest <https://github.com/EVerest/EVerest>`_
|
||||
|
||||
Stable Releases
|
||||
---------------
|
||||
|
||||
Stable releases are published every 6 months and represent thoroughly tested versions of EVerest. These releases:
|
||||
|
||||
- Follow a coordinated testing period
|
||||
- Receive community maintenance
|
||||
- Are tagged in Git with the format ``yyyy.mm.0``
|
||||
- Create a stable release branch for ongoing maintenance
|
||||
|
||||
Patch Releases
|
||||
--------------
|
||||
|
||||
Patch releases address bugs, security issues, and other critical fixes within a stable release line. These releases:
|
||||
|
||||
- Increment only the patch number (x)
|
||||
- Never introduce breaking changes to the :ref:`public API of EVerest <project-release-and-versioning-public-api>`
|
||||
- Are backported from the main development branch
|
||||
- Are tagged in Git with the incremented patch number
|
||||
|
||||
There is no fixed schedule for patch releases. They are published as needed to address issues in the stable release.
|
||||
|
||||
Development Versions
|
||||
--------------------
|
||||
|
||||
The ``main`` branch represents ongoing development work for the next stable release. Development versions may introduce breaking changes
|
||||
and new features that will be included in the next yyyy.mm.0 release.
|
||||
|
||||
.. _project-release-and-versioning-public-api:
|
||||
|
||||
Public API Definition
|
||||
=====================
|
||||
|
||||
EVerest's public API includes all interfaces that external users and integrators rely on. These APIs are subject to the stability guarantees
|
||||
described in this document.
|
||||
|
||||
The public API consists of:
|
||||
|
||||
- :doc:`External AsyncAPIs </explanation/adapt-everest/apis>`
|
||||
- :ref:`Energy Management JSON RPC API <everest_modules_RpcApi>`
|
||||
- Configuration and Storage contracts. As of today, this includes:
|
||||
- EVerest module configuration files (YAML or SQLite)
|
||||
- OCPP configuration (JSON or SQLite)
|
||||
|
||||
The individual public API components may maintain their own version numbers independent of the EVerest release version.
|
||||
|
||||
Please refer to :ref:`breaking changes <project-breaking-changes>` for detailed definitions of breaking changes within the public API.
|
||||
|
||||
.. attention::
|
||||
|
||||
Internal EVerest :doc:`interfaces </reference/interfaces_index>` and :doc:`types </reference/types_index>` are explicitly excluded from the public API
|
||||
and may change without notice.
|
||||
|
||||
The configuration and storage contracts of any Dummy and Simulation modules are explicitly excluded from the public API and may change without notice.
|
||||
|
||||
Stability Guarantees
|
||||
====================
|
||||
|
||||
Within a stable release branch (e.g., all ``2026.01.x`` versions), no :ref:`breaking changes <project-breaking-changes>` are backported to the
|
||||
public API. Patch releases within a stable line maintain full backward compatibility.
|
||||
|
||||
This guarantee means:
|
||||
|
||||
- All EVerest and OCPP Configuration as well as other file and path dependencies from ``2026.01.0`` work with ``2026.01.5``
|
||||
- External AsyncAPI clients compatible with ``2026.01.0`` work with all ``2026.01.x`` releases
|
||||
|
||||
EVerest makes a **best-effort attempt** to minimize breaking changes across major releases (e.g., from ``2026.01.x`` to ``2026.07.0``). However, breaking
|
||||
changes may be necessary for:
|
||||
|
||||
- Significant architectural enhancements
|
||||
- Protocol compliance updates
|
||||
- Deprecation of obsolete features
|
||||
|
||||
If upgrading across major releases, integrators should review the release notes and potential migration documentation.
|
||||
|
||||
Maintenance Policy
|
||||
==================
|
||||
|
||||
Infrastructure for Maintenance
|
||||
-------------------------------
|
||||
|
||||
The EVerest project **provides infrastructure** for stable release maintenance:
|
||||
|
||||
* Each stable release creates a dedicated branch (``stable/yyyy.mm``)
|
||||
* Stable branches remain open for community contributions
|
||||
* Critical security patches and bug fixes can be backported by project maintainers
|
||||
or community contributions
|
||||
|
||||
**Important:** The existence of a stable branch does not guarantee ongoing
|
||||
maintenance activity. Actual maintenance depends on community involvement and
|
||||
the availability of contributors and maintainers.
|
||||
|
||||
Active Maintenance Focus
|
||||
-------------------------
|
||||
|
||||
Project maintainers focus their efforts on:
|
||||
|
||||
* The **current stable release branch** - Active bug fixes and updates
|
||||
* The **main development branch** - New features and next release
|
||||
* **Security patches** - Backported to the current stable release on a best-effort basis
|
||||
|
||||
Older Stable Branches
|
||||
---------------------
|
||||
|
||||
Older stable release branches:
|
||||
|
||||
* Remain available for community-driven maintenance
|
||||
* May receive security patches at maintainer's discretion
|
||||
* Are supported by the community on a **best-effort basis**
|
||||
* Have no guaranteed response times or fix schedules
|
||||
|
||||
If your deployment relies on an older stable branch, we encourage you to
|
||||
contribute maintenance work back to the project.
|
||||
Reference in New Issue
Block a user