Add Power message and make Energy message broader (#267)

This PR addresses #261 and #262 by generalising the documentation of
the`Energy` Message and adding a `Power` message (so Power can be
represented in MW).

Author: camille-bouvy-frequenz

RELEASE_NOTES.md

@@ -12,6 +12,10 @@ Update of the `PaginationParams` struct.
 
 - Additional information for energy metric
 
+- Generalize Energy message documentation for broader market use
+
+- Add Power message to represent Power in MW
+
 ## Bug Fixes
 
 - Fix a dependency issue by pinning the `grpcio` version and related libraries.

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

@@ -1,4 +1,4 @@
-// Frequenz definitions of energy for electricity trading.
+// Frequenz definitions of energy.
 //
 // Copyright 2023 Frequenz Energy-as-a-Service GmbH
 //
@@ -14,11 +14,11 @@ import "frequenz/api/common/v1/types/decimal.proto";
 // Represents a single unit of electricity.
 //
 // !!! note
-//     In these trading orders, the unit of energy is denominated in MWh
-//     (Megawatt-hours) as opposed to MW (Megawatts).  MWh is a unit of energy
-//     representing total output over a period, while MW is a unit of power that
-//     represents the rate of energy production or consumption.
+//     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 {
-  // Represents energy unit in Megawatthours (MWh).
+  // Energy unit in Megawatthours (MWh).
   frequenz.api.common.v1.types.Decimal mwh = 1;
 }

proto/frequenz/api/common/v1/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.v1.market;
+
+import "frequenz/api/common/v1/types/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.v1.types.Decimal mw = 1;
+}