Reorganize releases notes on upgrading and new features

This commit reorganizes the release notes to move all "breaking changes"
to the Upgrading section, and to group changes by type (removal, rename,
renumbering and addition) and by protobuf package.

This hopefully will make easier for users to know how to deal with
changes and what new fetures are available, depending on which packages
they use/they are interested in.

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

RELEASE_NOTES.md

@@ -6,45 +6,83 @@
 
 ## Upgrading
 
-- The `ElectricalComponentStatus` enum has ben removed in favour of the `ElectricalComponentControlMode` enum.
+- Removed:
+
+    + `microgrid.components.ComponentStatus`, use `microgrid.electrical_components.ElectricalComponentControlMode` instead
+    + `ComponentErrorCode.UNDERVOLTAGE_SHUTDOWN`, use `ElectricalComponentDiagnosticCode.UNDERVOLTAGE` instead
+    + `microgrid.sensors.SensorMetric`, use `metrics.Metric` instead
+    + `microgrid.sensors.SensorMetricSample`, use `metrics.MetricSample` instead
+    + `microgrid.sensors.SensorCategory`, since it was not useful and potentially confusing
+
+        Sensors can report different sensor metrics, and they could belong to several of these categories simultaneously. This defeats the purpose of having singular categories for sensors. Some more useful categorization may be introduced again in the future.
+
+- Renamed several symbols to increase consistency and clarity:
+
+    + `microgrid.components`:
+
+        * The whole package and all proto files, messages, field, enums were renamed to `electrical_components`
+        * `ComponentCategoryMetadataVariant` to `ElectricalComponentCategorySpecificInfo`
+        * `Component.category_type` to `ElectricalComponent.category_specific_info`
+        * `ComponentCategoryMetadataVariant.metadata` to `ElectricalComponentCategorySpecificInfo.kind`
+        * `ComponentErrorCode` to `ElectricalComponentDiagnosticCode`
+        * `ComponentState` to `ElectricalComponentStateSnapshot`
+        * `ComponentState.sampled_at` to `ElectricalComponentStateSnapshot.origin_time`
+        * `ComponentData` to `ElectricalComponentTelemetry` (to better specify its purpose of encapsulating general telemetry data from electrical components)
+        * Grid-related terms to clarify their meaning and purpose:
+
+            + `COMPONENT_CATEGORY_GRID` to `ELECTRICAL_COMPONENT_CATEGORY_GRID_CONNECTION_POINT`
+            + `ComponentCategoryMetadataVariant.metadata.grid` to `ElectricalComponentCategorySpecificInfo.kind.grid_connection_point`
+
+    + `microgrid.sensors`:
+
+        * `SensorErrorCode` to `SensorDiagnosticCode`
+        * `SensorData` to `SensorTelemetry` (to better specify its purpose of encapsulating general telemetry data from sensors)
+        * `SensorState` to `SensorStateSnapshot`
+        * `SensorState.sampled_at` to `SensorStateSnapshot.origin_time`
+        * `SensorStateCode.SENSOR_STATE_CODE_ON` to `SensorStateCode.SENSOR_STATE_CODE_OK` (to better indicate that we do not control on/off state of sensors)
+
+    + `metrics`:
+
+        * The file `metric_sample.proto` to `metrics.proto`
+        * `MetricSample.source` to `MetricSample.connection`
+        * `MetricSample.sampled_at` to `sample_time`
+
+- Renumbered some enum values to remove unnecessary gaps:
+
+    + `microgrid.components.ComponentCategory` (`microgrid.electrical_components.ElectricalComponentCategory`)
+    + `microgrid.components.ComponentErrorCode` (`microgrid.electrical_components.ElectricalComponentDiagnosticCode`)
+    + `metrics.Metric`
 
 ## New Features
 
-- Renamed `components` to `electrical_components` and related messages, fields, enums.
-- Added message linking microgrid and sensor IDs.
-- Added new message definitions for communication components.
-- Added new message `ElectricalComponentDiagnostic` to represent warnings and errors in microgrid electrical components.
-- The enum `ComponentErrorCode` has now been renamed to `ElectricalComponentDiagnosticCode` to better reflect its shared usage with warnings and errors.
-- Added new message `SensorDiagnostic` to represent warnings and errors in microgrid sensors.
-- The enum `SensorErrorCode` has now been renamed to `SensorDiagnosticCode` to better reflect its shared usage with warnings and errors.
-- Added warnings to sensor `SensorState`.
-- Added a common `TimeIntervalFilter` message in `frequenz.api.common.v1.types` to standardize time interval filtering across APIs. This uses `start_time` (inclusive) and `end_time` (exclusive) fields, aligning with ISO 8601 and common programming conventions.
-- Added new message `CommunicationComponentDiagnostic` to represent warnings and errors in microgrid communication components.
-- Added new message `CommunicationComponentStateSnapshot` to represent the state of communication components.
-- Added new message definitions for streaming events (Deleted, Created, Updated)
-- Remove unnecessary gap in numbering in the `ElectricalComponentCategory` enum.
-- Renumber variants in the `Metric` enum to remove unnecessary gaps.
-- Renamed `metric_sample.proto` to `metrics.proto` to better reflect its content.
-- Renamed electrical component category `COMPONENT_CATEGORY_GRID` to `ELECTRICAL_COMPONENT_CATEGORY_GRID_CONNECTION_POINT` to clarify its meaning. Note that the change in the enum change is a part of a larger refactoring of the electrical component category enum.
-- The oneof variant `ComponentCategoryMetadataVariant.metadata.grid` has been renamed to `ElectricalComponentCategorySpecificInfo.info.grid_connection_point` to better reflect its purpose.
-- A new inverter type `INVERTER_TYPE_WIND_TURBINE` has been added to the `InverterType` enum.
-- Renamed `ComponentCategoryMetadataVariant` to `ElectricalComponentCategorySpecificInfo`.
-- Renamed field `ElectricalComponent.category_type` to `ElectricalComponent.category_specific_info` to better reflect its purpose.
-- Renamed `ElectricalComponentState` to `ElectricalComponentStateSnapshot` to better reflect its purpose.
-- Renamed `SensorState` to `SensorStateSnapshot` to better reflect its purpose.
-- Renamed `sampled_at` timestamps for state snapshots to `origin_time`.
-- Renamed `sampled_at` timestamps for metric samples to `sample_time`.
-- Remove `SensorMetricSample` in favour of using `MetricSample` for sensors.
-- Remove `SensorMetric` enum, since it was unused and redundant.
-- Renamed `MetricSample.source` to `MetricSample.connection` to make it more specific as to what it refers to.
-- Rename `SensorStateCode.SENSOR_STATE_CODE_ON` to `SensorStateCode.SENSOR_STATE_CODE_OK`, to better indicate that we do not control on/off state of sensors.
-- Rename `ComponentData` to `ElectricalComponentTelemetry` to better specify its purpose of encapsulating general telemetry data from electrical components.
-- Rename `SensorData` to `SensorTelemetry` to better specify its purpose of encapsulating general telemetry data from sensors.
-- The following changes have been made to the `ElectricalComponentDiagnosticCode` enum (previously `ComponentErrorCode`):
-    - The code `UNDERVOLTAGE_SHUTDOWN` has been removed in favour of `UNDERVOLTAGE`.
-    - New diagnostic codes have been added to cover more cases, especially for inverters.
-    - The codes have been renumbered.
-- Removed `SensorCategory` enum, since it was not useful and potentially confusing. Sensors can report different sensor metrics, and they could belong to several of these categories simultaneously. This defeats the purpose of having singular categories for sensors. We need to rethink how to categorize sensors. Until then, having it does not add any value, and therefore it has been removed.
+Added many new messages and enum values:
+
+- `microgrid.communication_components`: Package with message definitions for communication components
+
+    + `CommunicationComponentDiagnostic`: Message to represent warnings and errors in microgrid communication components
+    + `CommunicationComponentStateSnapshot`: Message to represent the state of communication components
+
+- `microgrid.electrical_components` (previously `microgrid.components`)
+
+    + `ElectricalComponentDiagnostic`: Message to represent warnings and errors in microgrid electrical components
+    + `ElectricalComponentDiagnosticCode` (previously `ComponentErrorCode`): New diagnostic codes to cover more cases, especially for inverters
+    + `InverterType.INVERTER_TYPE_WIND_TURBINE`: Enum value to represent wind turbine inverters
+
+- `microgrid.sensors`
+
+    + Message linking microgrid and sensor IDs
+    + `SensorDiagnostic`: Message to represent warnings and errors in microgrid sensors
+    + Added warnings to sensor `SensorState`
+
+- `streaming`: Package with message definitions for streaming events
+
+    + `Event`: Enum to represent different types of streaming events (Created, Deleted, Updated)
+
+- `types`
+
+    + `TimeIntervalFilter`: Message to standardize time interval filtering across APIs
+
+        This uses `start_time` (inclusive) and `end_time` (exclusive) fields, aligning with ISO 8601 and common programming conventions.
 
 ## Bug Fixes