From e9a348e778f497eef13ee5f8502d5b9dad880ab8 Mon Sep 17 00:00:00 2001
From: Flora <flora.hofmann@frequenz.com>
Date: Thu, 1 Aug 2024 12:17:41 +0200
Subject: [PATCH] Add additional info to inform energy metric users

Signed-off-by: Flora <flora.hofmann@frequenz.com>
---
 RELEASE_NOTES.md                              | 12 ++++++++++++
 src/frequenz/client/common/metric/__init__.py | 15 +++++++++++++--
 2 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index 4c64704e..ced4cc2b 100644
--- a/RELEASE_NOTES.md
+++ b/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)
diff --git a/src/frequenz/client/common/metric/__init__.py b/src/frequenz/client/common/metric/__init__.py
index 6b168d7f..ba276c36 100644
--- a/src/frequenz/client/common/metric/__init__.py
+++ b/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