From 90a509496530b4c00a04f29755c613e994122738 Mon Sep 17 00:00:00 2001
From: Anes Benmerzoug <a.benmerzoug@appliedai.de>
Date: Sat, 6 Apr 2024 13:47:37 +0200
Subject: [PATCH 1/3] Add section to contributing guide about adding notes for
 new features or changes

---
 CONTRIBUTING.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d2f47395f..365a5a605 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -314,6 +314,37 @@ that a link will remain valid, add a custom anchor to the section title:
 (note the space after the opening brace). You can then refer to it within
 another markdown file with `[Some section][permanent-anchor-to-some-section]`.
 
+### Adding notes about new features or changes
+
+We use the admonition extension of
+[Mkdocs Material](https://squidfunk.github.io/mkdocs-material/reference/admonitions/)
+to create admonitions, also known as call-outs, that hold information
+about when a certain feature was added or changed and optionally
+some description of the change. We put the admonition directly
+in a module's, a function's or class' docstring.
+
+For a new feature, we use the following admonition:
+
+```
+!!! tip "New in version <Version Number>"
+```
+
+For a change to an existing feature we use instead:
+
+```
+!!! tip "Changed in version <Version Number>"
+
+    <Description>
+```
+
+For example, for a change in version `1.2.3` that adds kwargs
+to a class' constructor we would write:
+
+```
+!!! tip "Changed in version 1.2.3"
+
+    Added kwargs to the constructor.
+```
 
 ### Using bibliography
 

From 6114366757d770c50b9629ce0bd6b1da60dc28d0 Mon Sep 17 00:00:00 2001
From: Anes Benmerzoug <a.benmerzoug@appliedai.de>
Date: Sat, 6 Apr 2024 13:54:17 +0200
Subject: [PATCH 2/3] Improve new contributing section

---
 CONTRIBUTING.md | 53 ++++++++++++++++++++++++++++++++++---------------
 1 file changed, 37 insertions(+), 16 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 365a5a605..56d8ead7b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -314,37 +314,58 @@ that a link will remain valid, add a custom anchor to the section title:
 (note the space after the opening brace). You can then refer to it within
 another markdown file with `[Some section][permanent-anchor-to-some-section]`.
 
-### Adding notes about new features or changes
+### Adding notes about new features, changes or deprecations
 
 We use the admonition extension of
 [Mkdocs Material](https://squidfunk.github.io/mkdocs-material/reference/admonitions/)
 to create admonitions, also known as call-outs, that hold information
-about when a certain feature was added or changed and optionally
-some description of the change. We put the admonition directly
+about when a certain feature was added, changed or deprecated and optionally
+a description with more details. We put the admonition directly
 in a module's, a function's or class' docstring.
 
-For a new feature, we use the following admonition:
+We use the following syntax:
 
 ```
-!!! tip "New in version <Version Number>"
+!!! tip "<Event Type> in version <Version Number>"
+
+    <Optional Description>
 ```
 
-For a change to an existing feature we use instead:
+The description is useful when the note is about a smaller change
+such as a parameter.
 
-```
-!!! tip "Changed in version <Version Number>"
+- For a new feature, we use:
 
-    <Description>
-```
+  ```
+  !!! tip "New in version <Version Number>"
+  
+      <Optional Description>
+  ```
 
-For example, for a change in version `1.2.3` that adds kwargs
-to a class' constructor we would write:
+- For a change to an existing feature we use:
 
-```
-!!! tip "Changed in version 1.2.3"
+  ```
+  !!! tip "Changed in version <Version Number>"
 
-    Added kwargs to the constructor.
-```
+      <Optional Description>
+  ```
+
+  For example, for a change in version `1.2.3` that adds kwargs
+  to a class' constructor we would write:
+
+  ```
+  !!! tip "Changed in version 1.2.3"
+
+      Added kwargs to the constructor.
+  ```
+
+- For a deprecation we use:
+
+  ```
+  !!! tip "Deprecated in version <Version Number>"
+
+      <Optional Description>
+  ```
 
 ### Using bibliography
 

From f6a415da84ec975e71068175849182049b8e9e6d Mon Sep 17 00:00:00 2001
From: Anes Benmerzoug <a.benmerzoug@appliedai.de>
Date: Sat, 6 Apr 2024 13:55:40 +0200
Subject: [PATCH 3/3] Update changelog

---
 CHANGELOG.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 92700d296..28a6635f3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,8 @@
   [PR #543](https://github.com/aai-institute/pyDVL/pull/543)
 - Glossary of data valuation and influence terms in the documentation
   [PR #537](https://github.com/aai-institute/pyDVL/pull/537
+- Documentation about writing notes for new features, changes or deprecations.
+  [PR #557](https://github.com/aai-institute/pyDVL/pull/557)
 
 ### Fixed