From 110c5ea351297c2e371ef7ea5b44fe32aa00b7b7 Mon Sep 17 00:00:00 2001
From: Christoph Ladurner <christoph.ladurner@tugraz.at>
Date: Mon, 11 Mar 2024 10:30:30 +0100
Subject: [PATCH] init: upgrade to v12

---
 docs/releases/upgrading/upgrade-v12.0.md | 138 +++++++++++++++++++++++
 1 file changed, 138 insertions(+)
 create mode 100644 docs/releases/upgrading/upgrade-v12.0.md

diff --git a/docs/releases/upgrading/upgrade-v12.0.md b/docs/releases/upgrading/upgrade-v12.0.md
new file mode 100644
index 00000000..366319f8
--- /dev/null
+++ b/docs/releases/upgrading/upgrade-v12.0.md
@@ -0,0 +1,138 @@
+# Upgrading from v11 to v12
+
+## Prerequisites
+
+The steps listed in this article require an existing local installation of InvenioRDM v11.
+
+!!! warning "Backup"
+
+    Always backup your database and files before you try to perform an upgrade.
+
+!!! info "Older Versions"
+
+    In case you have an InvenioRDM installation older than v11, you can gradually upgrade
+    using the existing infrastructure to v11 and afterwards continue from here.
+
+## Upgrade Steps
+
+!!! warning "Upgrade your invenio-cli"
+
+    Make sure you have the latest `invenio-cli` installed. For InvenioRDM v12 it is v1.2.0
+    
+    ```bash
+    $ invenio-cli --version
+    invenio-cli, version 1.
+    ```
+    
+!!! info "Virtual environments"
+
+    In case you are not inside a virtual environment, make sure that you prefix each `invenio`
+    command with `pipenv run`.
+
+
+**Local development**
+
+Changing the Python version in your development environment highly
+depends on your setup, and there is no golden rule.
+One example would be to use [PyEnv](https://github.com/pyenv/pyenv).
+
+You should delete your virtualenv before running `invenio-cli` or `pipenv` commands below.
+
+!!! warning "Risk of losing data"
+
+    Your virtual env folder contains uploaded files in InvenioRDM, in `var/instance/data`.
+    If you need to keep such files, make sure you copy them over to the new virtual env in the same location.
+
+### Upgrade InvenioRDM
+
+(TODO: should we write that 3.9<=X<=3.12 is possible?)
+Make sure that your virtual env is now running with Python 3.9.
+
+Upgrade the RDM version:
+
+```bash
+cd <my-site>
+# Upgrade to InvenioRDM v12
+invenio-cli packages update 12.0.0
+pipenv uninstall flask-babelex
+# Re-build assets
+invenio-cli assets build
+```
+
+Optionally, update the file `<my-site>/Pipfile`. Attention: this action might lead to
+installing unwanted pre-releases of other packages.
+
+```diff
+[packages]
+---invenio-app-rdm = {extras = [...], version = "~=11.0.0"}
++++invenio-app-rdm = {extras = [...], version = "~=12.0.0"}
+
+[pipenv]
+allow_prereleases = true
+```
+
+### Database migration
+
+Execute the database migration:
+
+```bash
+# Execute the database migration
+invenio alembic upgrade
+```
+
+### Declare usage statistics processing queues
+
+```shell
+invenio queues declare
+```
+
+### Update indices mappings
+
+```shell
+invenio index update communities-communities-v1.0.0
+invenio index update rdmrecords-drafts-draft-v5.0.0
+invenio index update rdmrecords-records-record-v5.0.0
+```
+
+CAVEAT: this is not working because of an permission problem in
+[invenio-search](https://github.com/inveniosoftware/invenio-search/blob/d8b23ecf48f63d8d313f90fd4618a480e15fbd7b/invenio_search/ext.py#L448).
+The only way to solve it is to destroy the index and reinit and
+rebuild it from scratch. This is possible now. Be aware of that it is
+not a good idea after v12 to purge the index because in v12 the
+statistics are keep in opensearch indices!!!
+
+
+### Data migration
+
+Execute the data migration, note that there is no need to re-index the data:
+
+```bash
+pipenv run invenio shell $(find $(pipenv --venv)/lib/*/site-packages/invenio_app_rdm -name migrate_11_0_to_12_0.py)
+```
+
+### New roles
+
+```bash
+invenio roles create administration-moderation
+invenio roles create administration
+
+invenio access allow administration-moderation role administration-moderation
+invenio access allow administration-access role administration
+invenio access allow superuser-access role administration
+```
+
+### New configuration variables
+
+```bash
+COMMUNITIES_IDENTITIES_CACHE_REDIS_URL = "URI_TO_REDIS"
+USERS_RESOURCES_ADMINISTRATION_ENABLED = True
+```
+
+## Big Changes
+
+- remove: dependency of flask-babelex
+- add: concept doi (aka parent doi)
+- add: statistics. (NOTE: statistic is stored in opensearch/libresearch -> NOT persistent)!
+- add: administration panel
+- add: set quota
+- add: branded communities