update docs and changelog (#880)

bihealth · Jan 9, 2024 · 5feff95 · 5feff95
1 parent 4466760
commit 5feff95
Show file tree

Hide file tree

Showing 6 changed files with 73 additions and 7 deletions.
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -5,6 +5,19 @@ Changelog for the **SODAR Core** Django app package. Loosely follows the
 `Keep a Changelog <http://keepachangelog.com/en/1.0.0/>`_ guidelines.
 
 
+Unreleased
+==========
+
+Changed
+-------
+
+- **General**
+    - Upgrade minimum Django version to v4.2.9 (#880)
+    - Upgrade minimum PostgreSQL version to v12 (#1074)
+    - Upgrade to PostgreSQL v16 in CI (#1074)
+    - Add Python v3.11 support (#1157)
+
+
 v0.13.3 (2023-12-06)
 ====================
 

diff --git a/docs/source/app_projectroles_settings.rst b/docs/source/app_projectroles_settings.rst
@@ -478,6 +478,13 @@ This part of the setup is **optional**.
 SAML SSO Configuration (Optional)
 =================================
 
+.. danger::
+
+    In the current dev version of SODAR Core (v1.1.0-WIP), SAML support has been
+    temporarily disabled. The repository must be upgraded to a new SAML library
+    with support for Django v4.2+. This may also cause changes for configuring
+    SAML authentication.
+
 Optional Single Sign-On (SSO) authorization via SAML is also available. To
 enable this feature, set ``ENABLE_SAML=1`` in your environment. Configuring SAML
 for SSO requires proper configuration of the Keycloak SSO server and the SAML

diff --git a/docs/source/dev_project_app.rst b/docs/source/dev_project_app.rst
@@ -53,7 +53,7 @@ to set up a fresh app generated in the standard way with
 
 It is also assumed that apps are more or less created according to best
 practices defined by `Two Scoops <https://www.twoscoopspress.com/>`_, with the
-use of `Class-Based Views <https://docs.djangoproject.com/en/3.2/topics/class-based-views//>`_
+use of `Class-Based Views <https://docs.djangoproject.com/en/4.2/topics/class-based-views/>`_
 being a requirement.
 
 
@@ -96,7 +96,7 @@ To provide a unique identifier for objects in the SODAR context, add a
 
     When updating an existing Django model with an existing database, the
     ``sodar_uuid`` field needs to be populated. See
-    `instructions in Django documentation <https://docs.djangoproject.com/en/3.2/howto/writing-migrations/#migrations-that-add-unique-fields>`_
+    `instructions in Django documentation <https://docs.djangoproject.com/en/4.2/howto/writing-migrations/#migrations-that-add-unique-fields>`_
     on how to create the required migrations.
 
 Model Example

diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst
@@ -56,9 +56,9 @@ your Django site are listed below. For a complete requirement list, see the
 - Ubuntu (20.04 Focal recommended and supported) / CentOS 7
 - System library requirements (see the ``utility`` directory and/or your own
   Django project)
-- Python >=3.8 (**NOTE:** Python 3.7 no longer supported in SODAR Core v0.10.8+)
-- Django 3.2
-- PostgreSQL >=11 and psycopg2-binary
+- Python 3.8-3.11 (3.11 recommended)
+- Django 4.2
+- PostgreSQL >=12 and psycopg2-binary
 - Bootstrap 4.x
 - JQuery 3.3.x
 - Shepherd and Tether

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -79,8 +79,8 @@ Python Programming
   any.
 
 Django Development
-  For learning about Django, head over to the `excellent documentation of the
-  Django Project <https://docs.djangoproject.com/en/3.2/>`_.
+  For learning about Django, head over to the
+  `official Django documentation <https://docs.djangoproject.com/en/4.2/>`_.
 
 HTML / Javascript / CSS / Bootstrap 4
   Together with Django, SODAR Core provides a framework to plug in your own

diff --git a/docs/source/major_changes.rst b/docs/source/major_changes.rst
@@ -10,6 +10,52 @@ older SODAR Core version. For a complete list of changes in current and previous
 releases, see the :ref:`full changelog<changelog>`.
 
 
+v1.0.0 (WIP)
+************
+
+Release Highlights
+==================
+
+- Upgrade to Django v4.2 and Postgres v16
+- Add Python 3.11 support
+
+Breaking Changes
+================
+
+Django v4.2 Upgrade
+-------------------
+
+This release updates SODAR Core from Django v3.2 to v4.2. This is a breaking
+change which causes many updates and also potentially requires updating several
+dependencies.
+
+To upgrade, please update the Django requirement along with your site's other
+Python requirements to match ones in ``requirements/*.txt``. See
+`Django deprecation documentation <https://docs.djangoproject.com/en/dev/internals/deprecation/>`_
+for details about what has been deprecated in Django and which changes are
+mandatory.
+
+Common known issues:
+
+- Minimum version of PostgreSQL has been bumped to v12.
+- Replace ``django.utils.translation.ugettext_lazy`` imports with
+  ``gettext_lazy``.
+- Replace ``django.conf.urls.url`` imports with ``django.urls.re_path``.
+- Calls for ``related_managers`` for unsaved objects raises ``ValueError``. This
+  can be handled by e.g. calling ``model.save(commit=False)`` before trying to
+  access foreign key relations.
+
+System Prerequisites
+--------------------
+
+The minimum required PostgreSQL version has been bumped to v12. In CI we
+currently use PostgreSQL v16, but anything from v12 to above should work with
+this SODAR Core release.
+
+Python v3.11 support has been officially added in this version. Also, 3.11 is
+now the recommended Python version to be used.
+
+
 v0.13.3 (2023-12-06)
 ********************