BU-ISCIII · saramonzon · Aug 4, 2026 · Aug 4, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [3.1.1dev] - 2026-06-18 : <https://github.com/BU-ISCIII/iskylims/compare/3.1.0...develop>
+## [3.1.1] - 2026-06-18 : <https://github.com/BU-ISCIII/iskylims/compare/3.1.0...3.1.1>
 
 ### Credits
 

diff --git a/LEAME.md b/LEAME.md
@@ -15,7 +15,6 @@ Esta guia es para la actualizacion del despliegue institucional de iSkyLIMS usan
   - [Configurar `my_prod_settings_iskylims.txt`](#configurar-my_prod_settings_iskylimstxt)
   - [Backup antes de actualizar](#backup-antes-de-actualizar)
   - [Ejecutar la actualizacion](#ejecutar-la-actualizacion)
-  - [Caso especial: actualizacion desde 3.0.0 a 3.1.0](#caso-especial-actualizacion-desde-300-a-310)
   - [Comprobaciones posteriores](#comprobaciones-posteriores)
   - [Rollback](#rollback)
   - [Reparar permisos](#reparar-permisos)
@@ -236,32 +235,7 @@ El script:
 
 No usa la accion `install` porque este procedimiento asume una base de datos institucional ya existente.
 
-## Caso especial: actualizacion desde 3.0.0 a 3.1.0
-
-La actualizacion desde 3.0.0 a 3.1.0 requiere pasos extra porque hay cambios de datos que necesitan scripts especificos:
-
-- `convert_rawtop_counter_to_int` antes de migraciones;
-- `library_pool_to_many_relation` despues de migraciones;
-- exportar antes la relacion `wetlab_library_pool.id -> run_process_id_id`.
-
-Exporta el fichero necesario:
-
-```bash
-mysql --user=<usuario_db> --password --host=<host_db> --port=<puerto_db> iskylims \
-  -e "SELECT id, run_process_id_id FROM wetlab_library_pool" \
-  > /tmp/library_pool_run_process.tsv
-```
-
-Ejecuta la actualizacion especial:
-
-```bash
-bash container_install.sh --engine podman --install_conf conf/my_prod_settings_iskylims.txt --action upgrade \
-  --script_before convert_rawtop_counter_to_int \
-  --script_after library_pool_to_many_relation,/tmp/library_pool_run_process.tsv \
-  2>&1 | tee ./iskylims_podman_upgrade_3_0_0_to_3_1_0_$(date +%Y%m%d_%H%M%S).log
-```
-
-Usa este comando solo para esa actualizacion concreta. Para actualizaciones posteriores, usa el comando generico de la seccion anterior.
+Si la version instalada necesita scripts de migracion de datos, sigue la [guia de actualizacion especifica para esa version](docs/upgrades/README.md) en lugar de ejecutar solamente el comando generico.
 
 ## Comprobaciones posteriores
 

diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 [![Django](https://img.shields.io/static/v1?label=Django&message=4.2&color=blue?style=plastic&logo=django)](https://github.com/django/django)
 [![Python](https://img.shields.io/static/v1?label=Python&message=3.8.10&color=green?style=plastic&logo=Python)](https://www.python.org/)
 [![Bootstrap](https://img.shields.io/badge/Bootstrap-v5.0-blueviolet?style=plastic&logo=Bootstrap)](https://getbootstrap.com)
-[![version](https://img.shields.io/badge/version-3.0.0-orange?style=plastic&logo=GitHub)](https://github.com/BU-ISCIII/iskylims.git)
+[![version](https://img.shields.io/badge/version-3.1.1-orange?style=plastic&logo=GitHub)](https://github.com/BU-ISCIII/iskylims.git)
 
 The introduction of massive sequencing (MS) in genomics facilities has meant an exponential growth in data generation, requiring a precise tracking system, from library preparation to fastq file generation, analysis and delivery to the researcher. Software designed to handle those tasks are called Laboratory Information Management Systems (LIMS), and its software has to be adapted to their own genomics laboratory particular needs. iSkyLIMS is born with the aim of helping with the wet laboratory tasks, and implementing a workflow that guides genomics labs on their activities from library preparation to data production, reducing potential errors associated to high throughput technology, and facilitating the quality control of the sequencing. Also, iSkyLIMS connects the wet lab with dry lab facilitating data analysis by bioinformaticians.
 
@@ -24,20 +24,13 @@ Application servers run web applications for bioinformatics analysis (GALAXY), t
       - [Cron jobs inside the container](#cron-jobs-inside-the-container)
     - [Manage containers after installation](#manage-containers-after-installation)
     - [Upgrade docker deployment](#upgrade-docker-deployment)
-    - [Upgrade docker deployment v3.0.0 to 3.1.0](#upgrade-docker-deployment-v300-to-310)
-      - [Back up first](#back-up-first)
-      - [Refresh code and settings](#refresh-code-and-settings)
   - [Bare-metal deployment (Ubuntu/CentOS)](#bare-metal-deployment-ubuntucentos)
     - [Install](#install)
       - [Clone the repository](#clone-the-repository)
       - [Prepare the database](#prepare-the-database)
       - [Configure install\_settings.txt](#configure-install_settingstxt)
       - [Run install.sh](#run-installsh)
-    - [Upgrade (3.0.0 to 3.1.0)](#upgrade-300-to-310)
-      - [Back up first](#back-up-first-1)
-      - [Refresh code and settings](#refresh-code-and-settings-1)
-      - [Run upgrade steps requiring root](#run-upgrade-steps-requiring-root)
-      - [Run upgrade steps without root](#run-upgrade-steps-without-root)
+    - [Upgrade bare-metal deployment](#upgrade-bare-metal-deployment)
   - [Common operations (Docker + bare-metal)](#common-operations-docker--bare-metal)
     - [Database creation, users and grants](#database-creation-users-and-grants)
     - [Backups](#backups)
@@ -323,40 +316,7 @@ bash container_install.sh --install_conf conf/my_prod_settings_iskylims.txt --ac
 
 The upgrade path rebuilds/restarts the container and runs `install.sh --bootstrap upgrade --tables` inside the app container. The app files are already baked into the rebuilt image; the bootstrap phase applies migrations with `--fake-initial`, refreshes `conf/first_install_tables.json`, refreshes static files, and skips superuser/demo/test data loading.
 
-### Upgrade docker deployment v3.0.0 to 3.1.0
-
-#### Back up first
-
-Run the backup steps in [Backups](#backups) first.
-
-For 3.0.0 -> 3.1.0, export the LibraryPool mapping first, then run the upgrade with pre/post scripts:
-
-```bash
-mysql --user=<db_user> --password=<db_password> --host=<db_server_ip> --port=<db_port> iskylims \
-  -e "SELECT id, run_process_id_id FROM wetlab_library_pool" \
-  > /tmp/library_pool_run_process.tsv
-```
-
-#### Refresh code and settings
-
-```bash
-cd <your working directory>/iskylims
-git pull
-cp conf/docker_production_settings.txt my_prod_settings_iskylims.txt
-sudo nano my_prod_settings_iskylims.txt
-```
-
-Ensure the file uses Linux-friendly encoding (UTF-8/ASCII) if you edit it on Windows.
-
-Keep the same `APP_UID`/`APP_GID` values in the selected install config before running the 3.0.0 -> 3.1.0 upgrade.
-
-Run upgrade command:
-
-```bash
-bash container_install.sh --engine podman --install_conf my_prod_settings_iskylims.txt --action upgrade \
-  --script_before convert_rawtop_counter_to_int \
-  --script_after library_pool_to_many_relation,/tmp/library_pool_run_process.tsv 2>&1 | tee ./iskylims_docker_install_$(date +%Y%m%d_%H%M%S).log
-```
+If the installed version requires data-migration scripts, follow the applicable [version-specific upgrade guide](docs/upgrades/README.md) instead of using only the generic command.
 
 ## Bare-metal deployment (Ubuntu/CentOS)
 
@@ -415,34 +375,9 @@ sudo bash install.sh --install full --git_revision main --tables
 
 - If Apache is managed elsewhere, skip the automatic restart with `--skip_apache_restart`.
 
-### Upgrade (3.0.0 to 3.1.0)
-
-Follow these steps to move from version 3.0.0 to the 3.1.x series.
-
-#### Back up first
-
-Run the backup steps in [Backups](#backups) first.
-- Additionally, back up the full installation folder (for example `/opt/iskylims`) for bare-metal rollback.
-- If you use library pools, export them before upgrading:
+### Upgrade bare-metal deployment
 
-  ```bash
-mysql --user=<db_user> --password=<db_password> --host=<db_server_ip> --port=<db_port> iskylims \
-  -e "SELECT id, run_process_id_id FROM wetlab_library_pool" \
-  > /tmp/library_pool_run_process.tsv
-  ```
-
-#### Refresh code and settings
-
-```bash
-cd <your working directory>/iskylims
-git pull
-cp conf/template_install_settings.txt install_settings.txt
-sudo nano install_settings.txt
-```
-
-Ensure the file uses Linux-friendly encoding (UTF-8/ASCII) if you edit it on Windows.
-
-#### Run upgrade steps requiring root
+Run the backup steps in [Backups](#backups) first and back up the full installation folder (for example `/opt/iskylims`). Then refresh the repository and review the current installation settings template before upgrading.
 
 Update system and Python dependencies:
 
@@ -452,19 +387,16 @@ sudo bash install.sh --upgrade dep 2>&1 | tee install_full.log
 
 Make sure the installation directory permissions allow the non-root step to write to `/opt/iskylims` (adapt your hardening script if paths changed).
 
-#### Run upgrade steps without root
-
 Upgrade the application code and database:
 
 ```bash
-# with library pool restore
-bash install.sh --upgrade app --git_revision main \
-  --script_before convert_rawtop_counter_to_int \
-  --script_after library_pool_to_many_relation,/tmp/library_pool_run_process.tsv
+bash install.sh --upgrade app --git_revision main
 ```
 
 Upgrades regenerate migrations and apply them with `--fake-initial` so existing tables remain intact, matching the Docker workflow.
 
+If the installed version requires data-migration scripts, follow the applicable [version-specific upgrade guide](docs/upgrades/README.md) instead of using only the generic command.
+
 ## Common operations (Docker + bare-metal)
 
 ### Database creation, users and grants

diff --git a/UPGRADE_SCRIPTS.md b/UPGRADE_SCRIPTS.md
@@ -1,6 +1,8 @@
 # Upgrade scripts
 
 This file lists data migration scripts and the version range they apply to.
+For complete operator procedures, prerequisites, and container or bare-metal commands, see the [version-specific upgrade guides](docs/upgrades/README.md).
+
 Run them with:
 
 ```bash

diff --git a/container_install.sh b/container_install.sh
@@ -1,6 +1,6 @@
 #!/usr/bin/bash
 
-ISKYLIMS_VERSION="3.1.0"
+ISKYLIMS_VERSION="3.1.1"
 
 usage() {
 cat << EOF

diff --git a/core/templates/core/footer.html b/core/templates/core/footer.html
@@ -31,7 +31,7 @@ <h6>Powered by</h6>
                 </div>
             </section>
             <section>
-                <p class="text-center">Version 3.1.0</p>
+                <p class="text-center">Version 3.1.1</p>
             </section>
         </div>
     </div>

diff --git a/docs/upgrades/2.3.0-to-3.0.0.md b/docs/upgrades/2.3.0-to-3.0.0.md
@@ -0,0 +1,23 @@
+# Upgrade from 2.3.0 to 3.0.0
+
+This upgrade includes application data changes that require dedicated Django scripts. Back up the database and installation before proceeding.
+
+## Migration scripts
+
+Run the following scripts as part of the upgrade:
+
+```bash
+python manage.py runscript rename_app_name
+python manage.py runscript migrate_sample_type
+python manage.py runscript migrate_optional_values
+```
+
+The scripts perform these changes:
+
+- `rename_app_name` updates stored application names after the iSkyLIMS application rename.
+- `migrate_sample_type` converts legacy SampleType optional-field indexes to the new mandatory-field names.
+- `migrate_optional_values` moves project option-list values into `SamplesProjectsTableOptions`.
+
+Run them against the upgraded application code and the intended production database. Verify the database backup and settings before executing them. The script inventory is maintained in [UPGRADE_SCRIPTS.md](../../UPGRADE_SCRIPTS.md).
+
+After completing this upgrade, follow the [3.0.0 to 3.1.0](3.0.0-to-3.1.0.md) guide before moving to later versions.
diff --git a/docs/upgrades/3.0.0-to-3.1.0.md b/docs/upgrades/3.0.0-to-3.1.0.md
@@ -0,0 +1,51 @@
+# Upgrade from 3.0.0 to 3.1.0
+
+This upgrade requires a data export and scripts on both sides of the database migrations. Back up the database, persistent documents, configuration, and installation files before proceeding.
+
+## Required order
+
+1. Export the existing LibraryPool-to-RunProcess mapping.
+2. Run `convert_rawtop_counter_to_int` before migrations.
+3. Apply the normal database migrations.
+4. Run `library_pool_to_many_relation` after migrations, passing the exported mapping.
+
+Export the mapping before changing the database schema:
+
+```bash
+mysql --user=<db_user> --password --host=<db_host> --port=<db_port> iskylims \
+  -e "SELECT id, run_process_id_id FROM wetlab_library_pool" \
+  > /tmp/library_pool_run_process.tsv
+```
+
+## Container deployment
+
+Keep the existing `APP_UID` and `APP_GID` values in the selected installation configuration. For rootless Podman, run:
+
+```bash
+bash container_install.sh --engine podman \
+  --install_conf conf/my_prod_settings_iskylims.txt \
+  --action upgrade \
+  --script_before convert_rawtop_counter_to_int \
+  --script_after library_pool_to_many_relation,/tmp/library_pool_run_process.tsv \
+  2>&1 | tee ./iskylims_podman_upgrade_3_0_0_to_3_1_0_$(date +%Y%m%d_%H%M%S).log
+```
+
+For Docker, replace `--engine podman` with `--engine docker` and use the appropriate installation configuration path.
+
+## Bare-metal deployment
+
+Update dependencies first:
+
+```bash
+sudo bash install.sh --upgrade dep 2>&1 | tee install_full.log
+```
+
+Then upgrade the application and run the scripts in their required order:
+
+```bash
+bash install.sh --upgrade app --git_revision 3.1.0 \
+  --script_before convert_rawtop_counter_to_int \
+  --script_after library_pool_to_many_relation,/tmp/library_pool_run_process.tsv
+```
+
+Use this special procedure only when crossing from `3.0.0` to `3.1.0`. Later upgrades should use the generic instructions unless another version-specific guide says otherwise.
diff --git a/docs/upgrades/README.md b/docs/upgrades/README.md
@@ -0,0 +1,17 @@
+# Version-specific upgrade guides
+
+Use these guides when an upgrade crosses a version boundary that requires special data migration or preparation. For upgrades without a listed special path, use the generic procedure in the main [README](../../README.md). Institutional rootless Podman deployments should also follow the current operational guidance in [LEAME](../../LEAME.md).
+
+Always back up the database, application configuration, persistent documents, and installation files before upgrading.
+
+## Upgrade path
+
+Apply every relevant guide in order when skipping releases:
+
+1. [2.3.0 to 3.0.0](2.3.0-to-3.0.0.md)
+2. [3.0.0 to 3.1.0](3.0.0-to-3.1.0.md)
+3. 3.1.0 to 3.1.1: no special data-migration scripts are required; use the generic upgrade procedure.
+
+The supported historical starting point is written as `2.3.0`, rather than `2.x`, because that is the version explicitly documented by the migration scripts.
+
+For a developer-oriented inventory of all migration scripts, see [UPGRADE_SCRIPTS.md](../../UPGRADE_SCRIPTS.md).
diff --git a/install.sh b/install.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
 
-APP_VERSION="3.1.0"
+APP_VERSION="3.1.1"
 
 # usage: prints the command line help and usage examples.
 usage() {