Merge pull request #557 from aai-institute/doc/version-added-documentation

Add section to contributing guide about adding notes for new features…

Author: AnesBenmerzoug

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
 

CONTRIBUTING.md

@@ -314,6 +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, 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, 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.
+
+We use the following syntax:
+
+```
+!!! tip "<Event Type> in version <Version Number>"
+
+    <Optional Description>
+```
+
+The description is useful when the note is about a smaller change
+such as a parameter.
+
+- For a new feature, we use:
+
+  ```
+  !!! tip "New in version <Version Number>"
+  
+      <Optional Description>
+  ```
+
+- For a change to an existing feature we use:
+
+  ```
+  !!! tip "Changed 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:
+
+  ```
+  !!! 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