Clear release notes and add v1alpha8 package (#396)

Author: tiyash-basu-frequenz

RELEASE_NOTES.md

@@ -2,123 +2,16 @@
 
 ## Summary
 
-This release introduces several breaking changes, new features, and improvements to the existing API. The most significant changes include renaming and restructuring of the `components` package to `electrical_components`, the introduction of new diagnostic codes, and the addition of new messages for communication components and streaming events.
+<!-- Here goes a general summary of what this release is about -->
 
 ## Upgrading
 
-- 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`
-        * `ComponentCategory` to `ElectricalComponentCategory`
-        * `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)
-        * `ComponentData.states` to `ElectricalComponentTelemetry.state_snapshots`
-        * 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`
-        * `InverterType.INVERTER_TYPE_SOLAR` to `InverterType.INVERTER_TYPE_PV` (to align with the more colloquial term "PV inverter")
-        * `ComponentCategory.COMPONENT_CATEGORY_RELAY` to `ElectricalComponentCategory.ELECTRICAL_COMPONENT_CATEGORY_BREAKER` (to better align with the common terminology used in electrical engineering).
-        * All contents of all the files in the `electrical_components` directory (previously `components`) are now moved into the `electrical_components.proto` file.
-
-    + `microgrid.sensors`:
-
-        * `SensorErrorCode` to `SensorDiagnosticCode`
-        * `SensorData` to `SensorTelemetry` (to better specify its purpose of encapsulating general telemetry data from sensors)
-        * `SensorState` to `SensorStateSnapshot`
-        * `SensorData.states` to `SensorTelemetry.state_snapshots`
-        * `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`
-
-    + `metrics.Metric`:
-
-       * The enum variants to follow a more consistent naming scheme of core-concept to modifier.
-       * `METRIC_AC_APPARENT_POWER*` to `METRIC_AC_POWER_APPARENT*`
-       * `METRIC_AC_ACTIVE_POWER*` to `METRIC_AC_POWER_ACTIVE*`
-       * `METRIC_AC_REACTIVE_POWER*` to `METRIC_AC_POWER_REACTIVE*`
-       * `METRIC_AC_APPARENT_ENERGY*` to `METRIC_AC_ENERGY_APPARENT*`
-       * `METRIC_AC_ACTIVE_ENERGY*` to `METRIC_AC_ENERGY_ACTIVE*`
-       * `METRIC_AC_REACTIVE_ENERGY*` to `METRIC_AC_ENERGY_REACTIVE*`
-
-    + `types`:
-
-        * The whole package has been renamed to `type`.
-
-- Renumbered some enum values to remove unnecessary gaps:
-
-    + `microgrid.components.ComponentCategory` (`microgrid.electrical_components.ElectricalComponentCategory`)
-    + `microgrid.components.ComponentErrorCode` (`microgrid.electrical_components.ElectricalComponentDiagnosticCode`)
-    + `metrics.Metric`
-
-- The minimum allowed version of `protobuf` and `grpcio` has been updated to 6.31.1 and 1.72.1 respectively, you might also need to bump your dependencies accordingly.
-
-- The file `location.proto` has been moved to the `types` package, moving the message `Location` to `types.Location`.
-
-- The type of the field `metrics.MetricSample.connection` has been changed from `string` to `metrics.MetricConnection`. The latter is a newly added message that provides a better categorization of the connection type.
-
-- The `v1` package has been renamed to `v1alpha7`. The current `v1` package now consists of the contents the same directory from the v0.6.x branch, which is the latest stable version of the API.
-
-- The enum `ComponentCategory` (now `ElectricalComponentCategory`) has been extended with new variants.
+<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
 
 ## New Features
 
-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.ElectricalComponentCategory` (previously `microgrid.ComponentCategory`) has been extended with new enum values:
-    + `ELECTRICAL_COMPONENT_CATEGORY_PLC`
-    + `ELECTRICAL_COMPONENT_CATEGORY_STATIC_TRANSFER_SWITCH`
-    + `ELECTRICAL_COMPONENT_CATEGORY_UNINTERRUPTIBLE_POWER_SUPPLY`
-    + `ELECTRICAL_COMPONENT_CATEGORY_CAPACITOR_BANK`
-    + `ELECTRICAL_COMPONENT_CATEGORY_SMART_LOAD`
-    + `ELECTRICAL_COMPONENT_CATEGORY_WIND_TURBINE`
-
-- `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`
-
-    + `Interval`: Message to standardize time interval filtering across APIs
+- A new package `frequenz.api.common.v1alpha8` has been added.
 
-        This uses `start_time` (inclusive) and `end_time` (exclusive) fields, aligning with ISO 8601 and common programming conventions.
+## Bug Fixes
 
+<!-- Here goes notable bug fixes that are worth a special mention or explanation -->

proto/frequenz/api/common/v1alpha8/grid/delivery_area.proto

@@ -0,0 +1,62 @@
+// Frequenz definitions of grids as entities participating in trading.
+//
+// Copyright 2025 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1alpha8.grid;
+
+// CodeType specifies the type of identification code used for uniquely
+// identifying various entities such as delivery areas, market participants, and
+// grid components within the energy market. This enumeration aims to offer
+// compatibility across different jurisdictional standards.
+//
+// !!! note "Understanding Code Types"
+//     Different regions or countries may have their own standards for uniquely
+//     identifying various entities within the energy market. For example, in
+//     Europe, the Energy Identification Code (EIC) is commonly used for this
+//     purpose.
+//
+// !!! info "Extensibility"
+//     New code types can be added to this enum to accommodate additional
+//     regional standards, enhancing the API's adaptability.
+//
+// !!! caution "Validation Required"
+//     The chosen code type should correspond correctly with the `code` field in
+//     the relevant message objects, such as `DeliveryArea` or `Counterparty`.
+//     Failure to match the code type with the correct code could lead to
+//     processing errors.
+//
+enum EnergyMarketCodeType {
+  // Unspecified type. This value is a placeholder and should not be used.
+  ENERGY_MARKET_CODE_TYPE_UNSPECIFIED = 0;
+
+  // European Energy Identification Code Standard.
+  ENERGY_MARKET_CODE_TYPE_EUROPE_EIC = 1;
+
+  // North American Electric Reliability Corporation identifiers.
+  ENERGY_MARKET_CODE_TYPE_US_NERC = 2;
+}
+
+// DeliveryArea represents the geographical or administrative region, usually
+// defined and maintained by a Transmission System Operator (TSO), where
+// electricity deliveries for a contract occur.
+//
+// The concept is important to energy trading as it delineates the agreed-upon
+// delivery location. Delivery areas can have different codes based on the//
+// jurisdiction in which they operate.
+//
+// !!! note "Jurisdictional Differences"
+//     This is typically represented by specific codes according to local
+//     jurisdiction. In Europe, this is represented by an EIC
+//     (Energy Identification Code).
+message DeliveryArea {
+  // Code representing the unique identifier for the delivery area.
+  string code = 1;
+
+  // Type of code used for identifying the delivery area itself.
+  EnergyMarketCodeType code_type = 2;
+}

proto/frequenz/api/common/v1alpha8/grid/delivery_duration.proto

@@ -0,0 +1,61 @@
+// Frequenz definitions of the time increment used for electricity
+// deliveries and trading.
+//
+// Copyright 2025 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1alpha8.grid;
+
+import "google/protobuf/timestamp.proto";
+
+// DeliveryDuration represents the time increment, in minutes,
+// used for electricity deliveries and trading. These durations
+// serve as the basis for defining the delivery period in contracts,
+// and they dictate how energy is scheduled and delivered to meet
+// contractual obligations.
+//
+// !!! note "Compatibility Constraints"
+//     Not all delivery durations are universally
+//     compatible with all delivery areas or markets.
+//
+enum DeliveryDuration {
+  // Default value, indicates that the duration is unspecified.
+  DELIVERY_DURATION_UNSPECIFIED = 0;
+
+  // 5-minute duration
+  DELIVERY_DURATION_5 = 1;
+
+  // 15-minute contract duration.
+  DELIVERY_DURATION_15 = 2;
+
+  // 30-minute contract duration.
+  DELIVERY_DURATION_30 = 3;
+
+  // 1-hour contract duration.
+  DELIVERY_DURATION_60 = 4;
+}
+
+// DeliveryPeriod represents the time period during which the contract
+// is delivered. It is defined by a start timestamp and a duration.
+message DeliveryPeriod {
+  // Start UTC timestamp represents the beginning of the delivery period.
+  // This timestamp is inclusive, meaning that the delivery period starts
+  // from this point in time.
+  //
+  // !!! note
+  //     Delivery period start time constraints:
+  //     - 5-minute durations must start at times that are multiples of
+  //       5 minutes past the hour.
+  //     - 15-minute durations must start at :00, :15, :30, or
+  //       :45 past the hour.
+  //     - 30-minute durations must start at :00 or :30 past the hour.
+  //     - 60-minute durations must start at :00 past the hour.
+  google.protobuf.Timestamp start = 1;
+
+  // The length of the delivery period.
+  DeliveryDuration duration = 2;
+}

proto/frequenz/api/common/v1alpha8/market/energy.proto

@@ -0,0 +1,24 @@
+// Frequenz definitions of energy.
+//
+// Copyright 2025 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1alpha8.market;
+
+import "frequenz/api/common/v1alpha8/type/decimal.proto";
+
+// Represents a single unit of electricity.
+//
+// !!! note
+//     The unit of energy is denominated in MWh, which is a unit of energy
+//     representing total output over a period.(Megawatt-hours). This differs
+//     from MW (Megawatts), a unit of power representing the rate of energy
+//     production or consumption.
+message Energy {
+  // Energy unit in Megawatthours (MWh).
+  frequenz.api.common.v1alpha8.type.Decimal mwh = 1;
+}

proto/frequenz/api/common/v1alpha8/market/power.proto

@@ -0,0 +1,30 @@
+// Frequenz definitions of power.
+//
+// Copyright 2024 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1alpha8.market;
+
+import "frequenz/api/common/v1alpha8/type/decimal.proto";
+
+// Represents a single unit of power.
+//
+// !!! note
+//     The power unit is denominated in MW (Megawatts), which is a unit of
+//     power representing the rate of energy production or consumption at any
+//     given moment. This differs from MWh (Megawatt-hours), which measures
+//     the total amount of energy delivered or consumed over a period.
+//
+// Example:
+//     A power plant running at 10 MW for 1 hour generates 10 MWh of energy.
+//
+// This message standardizes the representation of power in MW across all
+// market applications.
+message Power {
+  // Power amount in Megawatts (MW).
+  frequenz.api.common.v1alpha8.type.Decimal mw = 1;
+}

proto/frequenz/api/common/v1alpha8/market/price.proto

@@ -0,0 +1,53 @@
+// Frequenz definitions of price for electricity trading.
+//
+// Copyright 2025 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1alpha8.market;
+
+import "frequenz/api/common/v1alpha8/type/decimal.proto";
+
+// Represents a monetary price for electricity trading, including
+// the amount and currency. The currency used should align with the
+// delivery area's standard currency.
+//
+// !!! caution "Validation Required"
+//     It's essential to ensure that the currency aligns with the
+//     standard currency of the associated delivery area. Failure to
+//     do so may result in the API service rejecting the request due to currency
+//     mismatches.
+//
+// !!! info "Relation to Delivery Area"
+//     The currency specified is intrinsically related to the delivery area
+//     for the contract. Make sure the chosen currency is compatible with
+//     the delivery area's currency standards.
+//
+message Price {
+  // List of supported currencies.
+  //
+  // !!! info "Extensibility"
+  //     New currencies can be added to this enum to support additional markets.
+  enum Currency {
+    CURRENCY_UNSPECIFIED = 0;
+    CURRENCY_USD = 1;
+    CURRENCY_CAD = 2;
+    CURRENCY_EUR = 3;
+    CURRENCY_GBP = 4;
+    CURRENCY_CHF = 5;
+    CURRENCY_CNY = 6;
+    CURRENCY_JPY = 7;
+    CURRENCY_AUD = 8;
+    CURRENCY_NZD = 9;
+    CURRENCY_SGD = 10;
+  }
+
+  // The amount of the price.
+  frequenz.api.common.v1alpha8.type.Decimal amount = 1;
+
+  // The currency in which the price is denominated.
+  Currency currency = 2;
+}

proto/frequenz/api/common/v1alpha8/metrics/bounds.proto

@@ -0,0 +1,23 @@
+// Definitions for bounds.
+//
+// Copyright:
+// Copyright 2025 Frequenz Energy-as-a-Service GmbH
+//
+// License:
+// MIT
+
+syntax = "proto3";
+
+package frequenz.api.common.v1alpha8.metrics;
+
+// A set of lower and upper bounds for any metric.
+// The units of the bounds are always the same as the related metric.
+message Bounds {
+  // The lower bound.
+  // If absent, there is no lower bound.
+  optional float lower = 1;
+
+  // The upper bound.
+  // If absent, there is no upper bound.
+  optional float upper = 2;
+}