From 9c0e4bcfeb21a00aaf075f91ae4cc4d7c944915d Mon Sep 17 00:00:00 2001
From: alejandromumo <manuel.alejandro.de.oliveira.da.costa@cern.ch>
Date: Fri, 11 Oct 2024 16:05:37 +0200
Subject: [PATCH 1/2] collections: added feature overview

---
 docs/releases/versions/version-v13.0.0.md | 83 +++++++++++++++++++++++
 1 file changed, 83 insertions(+)

diff --git a/docs/releases/versions/version-v13.0.0.md b/docs/releases/versions/version-v13.0.0.md
index 923dd8d2..2762b4c5 100644
--- a/docs/releases/versions/version-v13.0.0.md
+++ b/docs/releases/versions/version-v13.0.0.md
@@ -30,6 +30,89 @@ Searches like ` Universitatea "Dunărea de Jos” din Galați` now work [PR](htt
 
 BREAKING -> mapping changes, create new indices
 
+### Collections
+
+Collections are a "big" feature added to v13. 
+
+Collections are stored in the Database and each collection defines a search query string that is used to fetch each collection records. Find more information in the [RFC](https://github.com/inveniosoftware/rfcs/blob/master/rfcs/rdm-0079-collections.md).
+
+**How to create a collection for a community**
+
+Currently collections are created using a python shell (`invenio shell`)
+
+Requirements:
+
+- A community.
+- A collection tree that acts as the "root" node of the collection.
+
+If you do not have a collection tree, start by creating one:
+
+```python
+from invenio_rdm_records.collections.api import CollectionTree
+
+ctree = CollectionTree.create(
+    title="Programs", order=10, community_id="<community_uuid>", slug="programs"
+)
+```
+
+The `order` parameter controls the order that trees are rendered in the UI.
+
+Create a collection under `programs`:
+
+```python
+from invenio_rdm_records.proxies import current_rdm_records
+from invenio_access.permissions import system_identity
+
+collections_service = current_rdm_records.collections_service
+
+# Use another identity if needed
+identity = system_identity
+
+# Desired community ID
+community_id = "9d0d45ce-0ea9-424a-ab17-a72215b2e8c3"
+
+collection = collections_service.create(
+        identity,
+        community_id,
+        tree_slug="programs",
+        slug="h2020",
+        title="Horizon 2020",
+        query="metadata.funding.program:h2020",
+        order=10
+    )
+```
+
+For nested collections, the `add` service method can be used:
+
+```python
+
+h2020 = collections_service.read(
+    identity, community_id=community_id, tree_slug='programs', slug='h2020'
+)
+
+open_records = collections_service.add(
+        identity,
+        collection=h2020._collection,
+        slug="h-open-records",
+        title="Horizon 2020 (Open records)",
+        query="access.record:public",
+        order=20
+    )
+```
+
+All the service methods that create collections also implements the Unit of Work pattern, so it can used if transactional consistency is needed.
+
+The created collections can be accessed at:
+
+- https://127.0.0.1:5000/communities/<community_slug>/collections/h2020
+- https://127.0.0.1:5000/communities/<community_slug>/collections/h-open-records
+
+Adjust the URL and `community_slug` as needed.
+
+An overview of all the collections can be found in the community browse page (if enabled):
+
+- https://127.0.0.1:5000/communities/<community_slug>/browse
+
 ### Miscellaneous additions
 
 Here is a quick summary of the myriad other improvements in this release:

From b572347d64ec476f2583d2622537ca9a60d7630d Mon Sep 17 00:00:00 2001
From: alejandromumo <manuel.alejandro.de.oliveira.da.costa@cern.ch>
Date: Fri, 11 Oct 2024 16:09:36 +0200
Subject: [PATCH 2/2] collections: added warning message for DB upgrade

---
 docs/releases/versions/version-v13.0.0.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/releases/versions/version-v13.0.0.md b/docs/releases/versions/version-v13.0.0.md
index 2762b4c5..f35edd80 100644
--- a/docs/releases/versions/version-v13.0.0.md
+++ b/docs/releases/versions/version-v13.0.0.md
@@ -32,7 +32,9 @@ BREAKING -> mapping changes, create new indices
 
 ### Collections
 
-Collections are a "big" feature added to v13. 
+Collections are a "big" feature added to v13.
+
+!!!warning Collections require new database tables, therefore its migration recipes must be executed (`invenio db upgrade` or similar)
 
 Collections are stored in the Database and each collection defines a search query string that is used to fetch each collection records. Find more information in the [RFC](https://github.com/inveniosoftware/rfcs/blob/master/rfcs/rdm-0079-collections.md).