Add additional info to inform energy metric users

Signed-off-by: Flora <[email protected]>

Author: flora-hofmann-frequenz

RELEASE_NOTES.md

@@ -6,12 +6,24 @@
 
 ## Upgrading
 
+<<<<<<< HEAD
 * Upgrading metric `__init__` to names from api-common release [v0.6.0](https://github.com/frequenz-floss/frequenz-api-common/releases/tag/v0.6.0)
 
 ## New Features
 
 <!-- Here goes the main new features and examples or instructions on how to use them -->
+=======
+<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
+
+## New Features
+
+* Additional information for energy metric
+>>>>>>> fd64a93 (Add additional info to inform energy metric users)
 
 ## Bug Fixes
 
 <!-- Here goes notable bug fixes that are worth a special mention or explanation -->
+<<<<<<< HEAD
+=======
+
+>>>>>>> fd64a93 (Add additional info to inform energy metric users)

src/frequenz/client/common/metric/__init__.py

@@ -13,7 +13,18 @@
 
 
 class Metric(Enum):
-    """List of supported metrics."""
+    """List of supported metrics.
+
+    AC energy metrics information:
+    * This energy metric is reported directly from the component, and not a
+    result of aggregations in our systems. If a component does not have this
+    metric, this field cannot be populated.
+    * Components that provide energy metrics reset this metric from time to
+    time. This behaviour is specific to each component model. E.g., some
+    components reset it on UTC 00:00:00.
+    * This energy metric does not specify the timestamp since when the energy
+    was being accumulated, and therefore can be inconsistent.
+    """
 
     # Default value
     UNSPECIFIED = PBMetric.METRIC_UNSPECIFIED
@@ -57,7 +68,7 @@ class Metric(Enum):
     AC_POWER_FACTOR_PHASE_2 = PBMetric.METRIC_AC_POWER_FACTOR_PHASE_2
     AC_POWER_FACTOR_PHASE_3 = PBMetric.METRIC_AC_POWER_FACTOR_PHASE_3
 
-    # AC energy metrics
+    # AC energy metrics - Please be careful when using and check Enum docs
     AC_APPARENT_ENERGY = PBMetric.METRIC_AC_APPARENT_ENERGY
     AC_APPARENT_ENERGY_PHASE_1 = PBMetric.METRIC_AC_APPARENT_ENERGY_PHASE_1
     AC_APPARENT_ENERGY_PHASE_2 = PBMetric.METRIC_AC_APPARENT_ENERGY_PHASE_2