Ulmo Roles and Permissions release note

Author: sarina

source/_images/educator_how_tos/library_manage_access_button.png

@@ -4,27 +4,34 @@ Introducing the Administrative Console
 ######################################
 
 The Ulmo release introduces the first version of the Administrative Console, a
-central place where administrators can manage authorization for Open edX tools,
-starting with :ref:`Roles and Permissions <Ulmo Roles and Permissions>` over
-Libraries. The console is designed as an extensible UI that will later support
-additional administrative workflows and integrations. It is powered by the new
-roles and permissions model and is intended to serve as a general purpose admin
-surface.
+central place where administrators can manage access for Open edX tools,
+starting with :ref:`Ulmo Roles and Permissions`. The console is designed as an
+extensible UI that will later support additional administrative workflows and
+integrations. It is powered by the new roles and permissions model and is
+intended to serve as a general purpose admin tool.
 
 What is in Ulmo for the Administrative Console
 **********************************************
 
-In Ulmo, the Administrative Console focuses on managing access to libraries that use the new Roles and Permissions service:
+In Ulmo, the Administrative Console focuses on managing access to libraries that
+use the new Roles and Permissions service:
 
-* A library team manager that shows all users who have access to a library, the roles they hold, and the available role definitions.
+* A library team management page that shows all users who have access to a
+  library, the roles they hold, and the available role definitions.
 
-* A list of users who have access to libraries across the instance, including which libraries they can access and at what scope.
+* A list of users who have access to libraries across the instance, including
+  which libraries they can access and at what scope.
 
-* An overview of library roles and what each role allows a user to do in a library, for example view, edit, publish or manage the team.
+* An overview of :ref:`Library Roles <Ulmo Available RP>` and what each role
+  allows a user to do in a library, for example view, edit, publish or manage
+  the team.
 
-* Search and filters by user, email, role and library so administrators can quickly see who has access where.
+* Search and filters by user, email, role and library so administrators can
+  quickly see who has access where.
 
-* The ability to grant, update or revoke access by assigning or removing roles for a specific library. Users can hold more than one role and their effective access is the combination of those roles.
+* The ability to grant, update or revoke access by assigning or removing roles
+  for a specific library. Users can hold more than one role and their effective
+  access is the combination of those roles.
 
 How to Access the Administrative Console
 ****************************************
@@ -34,12 +41,16 @@ How to Access the Administrative Console
    .. image:: /_images/release_notes/ulmo/admin_console_1.png
        :alt: Studio Homepage, with a Library highlighted
 
-#. Use the :guilabel:`Manage Access` button in the right tray for that library to open the Administrative Console in a new tab, already focused on that library.
+#. Use the :guilabel:`Manage Access` button in the right tray for that library
+   to open the Administrative Console in a new tab, already focused on that
+   library.
 
    .. image:: /_images/release_notes/ulmo/admin_console_2.png
        :alt: A Library in Studio, with the right tray open. The Manage Access button is highlighted
 
-#. From this view, Library Admins and global admins can review the team, adjust roles and confirm that access looks correct.
+#. From this view, Library Admins and global admins can review the team, adjust
+   roles and confirm that access looks correct. See :ref:`Add users to
+   Libraries` for more detail.
 
    .. image:: /_images/release_notes/ulmo/admin_console_3.png
        :alt: The Administrative Console, showing the Library Team Management for the specified library. You can see all users names, emails, and Roles, and take Edit action if you have permissions to edit roles
@@ -56,24 +67,31 @@ management for libraries moves into the Administrative Console.
 Out of Scope
 ************************
 
-The following capabilities are not included in this first release of the Administrative Console:
+The following capabilities are not included in this first release of the
+Administrative Console:
 
 * Managing access for courses, forums or other areas beyond Libraries.
 
-* Managing platform settings that are not related to access, such as general configuration, integrations or content settings.
+* Managing platform settings that are not related to access, such as general
+  configuration, integrations or content settings.
 
 Future Improvements
 *******************
 
-After Ulmo, the Administrative Console is expected to evolve in several directions:
+After Ulmo, the Administrative Console is expected to evolve in several
+directions:
 
-* Hosting additional Roles and Permissions scopes such as courses, forums or other product areas.
+* Hosting additional Roles and Permissions scopes such as courses, forums or
+  other product areas.
 
-* Introducing richer administration views that span multiple scopes, for example, seeing a user's access across libraries and courses in one place.
+* Introducing richer administration views that span multiple scopes, for
+  example, seeing a user's access across libraries and courses in one place.
 
-* Adding other platform level configuration panels, for example user groups or external integrations.
+* Adding other platform level configuration panels, for example user groups or
+  external integrations.
 
-This release focuses on delivering value for library access management while preparing the architecture for future extensions.
+This release focuses on delivering value for library access management while
+preparing the architecture for future extensions.
 
 .. seealso::
 

source/_images/educator_how_tos/library_team_button.png

@@ -4,56 +4,91 @@ Roles and Permissions in Libraries
 #######################################
 
 The Ulmo release introduces the first phase of the new roles and permissions
-system for the Open edX platform. This MVP focuses on establishing a shared
-authorization service and connecting it to the latest version of Libraries, so
-the same model can be extended to other parts of the platform over time.
+system for the Open edX platform. This first phase focuses on establishing a
+shared roles & permissions service and connecting it to Libraries, so the same
+model can be extended to other parts of the platform over time.
+
+.. image:: /_images/educator_how_tos/library_team_member_tab.png
+   :alt: The Team Members tab of the Admin Console, showing two team members in a table with the columns Name, Email, Role, and Actions
+   :width: 800
 
 Any user who has a role in a library can open the library team manager in the
 new Administrative Console from Studio. This view shows all members of the
 library, the role each person holds, and the permissions associated with each
-role. Library Admins and global admins can use this view to assign or revoke
+role. Library Admins and global site admins can use this view to assign or revoke
 roles for that library, so team membership and role information live in a single
 place.
 
 The goal of the Ulmo MVP is to introduce the new roles and permissions model to
 Libraries with functional parity and a clearer model of roles, not to change how
-authors create or reuse content. 
+authors create or reuse content.
+
+.. admonition:: Migrate Legacy Libraries
+
+    :ref:`Legacy Libraries <Legacy Content Libraries Overview>` do not support the new Roles & Permissions functionality.
+    Upgrade Legacy Libraries in order to take advantage of this new feature!
+    To learn more view the :ref:`migration documentation <Migrating Legacy Libraries>`.
+
+.. _Ulmo Available RP:
 
 What's Available in Ulmo
 ************************
 
 The Ulmo release includes:
 
-* **Library scoped roles**: Library Admin, Library Author, Library Contributor
-  and Library User, each mapped to a defined set of permissions that control who
-  can view, edit, publish or reuse library content, and who can manage the
-  library team.
-
-* A new **Library Contributor** role that matches most of the Library Author
+* Library scoped roles (:ref:`authz:Library Roles`): Library Admin, Library Author,
+  Library Contributor, and Library User, each mapped to a defined set of
+  permissions that control who can view, edit, publish or reuse library content,
+  and who can manage the library team.
+
+  .. table:: Matrix of Content Library Roles and Permissions
+    :widths: auto
+
+    ============================================= ================= ================ ===================== ==============
+    Permissions                                   Library Admin     Library Author   Library Contributor   Library User
+    ============================================= ================= ================ ===================== ==============
+    **Library**
+    --------------------------------------------- ----------------- ---------------- --------------------- --------------
+    content_libraries.view_library                ✅                ✅               ✅                    ✅
+    content_libraries.manage_library_tags         ✅                ✅               ✅                    ❌
+    content_libraries.delete_library              ✅                ❌               ❌                    ❌
+    **Content**
+    --------------------------------------------- ----------------- ---------------- --------------------- --------------
+    content_libraries.edit_library_content        ✅                ✅               ✅                    ❌
+    content_libraries.publish_library_content     ✅                ✅               ❌                    ❌
+    content_libraries.reuse_library_content       ✅                ✅               ✅                    ✅
+    **Team**
+    --------------------------------------------- ----------------- ---------------- --------------------- --------------
+    content_libraries.view_library_team           ✅                ✅               ✅                    ✅
+    content_libraries.manage_library_team         ✅                ❌               ❌                    ❌
+    **Collections**
+    --------------------------------------------- ----------------- ---------------- --------------------- --------------
+    content_libraries.create_library_collection   ✅                ✅               ✅                    ❌
+    content_libraries.edit_library_collection     ✅                ✅               ✅                    ❌
+    content_libraries.delete_library_collection   ✅                ✅               ✅                    ❌
+    ============================================= ================= ================ ===================== ==============
+
+* A new "Library Contributor" role that matches most of the Library Author
   capabilities for creating and editing content, managing tags and collections,
-  and reusing content, but cannot publish content.
-
-* Enforcement of these permissions when users view a library, edit draft
-  content, publish content, manage tags and collections, reuse library content
-  in courses, or manage the library team.
+  and reusing content, but cannot publish content. They support the authoring
+  process while leaving final publishing to Authors or Admins.
 
-* A library team manager in the :ref:`Administrative Console <Ulmo console>`.
+* A library team management page in the :ref:`Administrative Console <Ulmo console>`.
   Any user who has a role in a library can open this view to see all members,
   their roles and the available role definitions. Library Admins and global
-  admins use the same view to assign or revoke roles for that library, so team
+  site admins use the same view to assign or revoke roles for that library, so team
   membership and role information are managed from a single place.
 
-* A migration tool that replicates existing library roles into the new system,
+* An automatic migration that replicates existing library roles into the new system,
   so current configurations are preserved without manual changes.
 
 Scope and Impact
 ****************
 
 The new roles and permissions system applies only to Content Libraries, not
 :ref:`Legacy Libraries <Legacy Content Libraries Overview>`. It replaces the
-previous library specific authorization logic with library-scoped roles managed
-by the shared authorization service and surfaced through the :ref:`Administrative
-Console <Ulmo console>`.
+previous library specific permissions logic with library-scoped roles surfaced
+through the :ref:`Administrative Console <Ulmo console>`.
 
 The scope of this release is limited to:
 
@@ -74,44 +109,47 @@ The following areas are not affected in Ulmo:
 Migration of Existing Library Access
 ************************************
 
-Ulmo includes a migration path for existing library access configurations.
+Ulmo includes an automated migration path for existing library access
+configurations.
 
-During the upgrade, current library role assignments are mapped into the new
-roles & permissions system by the migration tool. The intent is to preserve who can
-access each library and what they can do, without requiring manual configuration
-from platform operators.
+During the upgrade to Ulmo, current library role assignments are mapped into the
+new roles & permissions system automatically via the Ulmo upgrade. The intent is
+to preserve who can access each library and what they can do, without requiring
+manual configuration from platform operators.
 
-After the upgrade, operators can review library teams in the Administrative
-Console to confirm that roles and access levels look correct. For most
-deployments that already use Libraries, no additional action should be required
-beyond this validation step.
+After the upgrade, operators and Library owners can review library teams in the
+Administrative Console to confirm that roles and access levels look correct. For
+most deployments that already use Libraries, no additional action should be
+required beyond this validation step.
 
 Future improvements
 *******************
 
 After Ulmo, the Roles and Permissions work is expected to evolve in several
 directions:
 
-Extending the same Roles & Permissions model beyond Libraries. Course authoring is the
-next candidate, and future phases will expand the roles and permissions pattern
-to the LMS, forums, and other product areas.
+* Extending the same Roles & Permissions model beyond Libraries. Course
+  authoring is the next candidate, and future phases will expand the roles and
+  permissions pattern to Studio, forums, and other product areas.
 
-Introducing more advanced administration features in the Administrative Console,
-allowing for managing multiple scopes at once, listing users' roles across
-scopes, and granting roles to multiple scopes in one action.
+* Introducing more advanced administration features in the Administrative
+  Console, allowing for managing multiple scopes at once, listing users' roles
+  across scopes, and granting roles to multiple scopes in one action.
 
-Exploring support for custom roles, based on feedback from operators who manage
-large instances.
+* Exploring support for custom roles, based on feedback from operators who
+  manage large instances.
 
 These improvements will be scoped and tracked in future releases once the
-Libraries integration is validated in production.
+Libraries integration is validated in production. Be sure to :ref:`Verawood planning`!
 
 .. seealso::
 
    :ref:`Ulmo console`
 
    :ref:`Add users to Libraries`
 
+   :ref:`authz:Roles Permissions Content Library`
+
    :ref:`Migrating Legacy Libraries`
 
 

source/community/release_notes/ulmo/ulmo_console.rst

@@ -1,3 +1,5 @@
+.. _Verawood planning:
+
 Stay Up To Date with Verawood
 ##############################
 
@@ -22,5 +24,5 @@ Join asynchronously in the `#release-planning room in Slack <openedx.org/slack>`
 +--------------+-------------------------------+----------------+--------------------------------+
 | Review Date  | Working Group Reviewer        |   Release      |Test situation                  |
 +--------------+-------------------------------+----------------+--------------------------------+
-|  2025-04-15  | sarina                        | Sumac          |   Pass                         |
+|  2025-04-15  | sarina                        | Ulmo           |   Pass                         |
 +--------------+-------------------------------+----------------+--------------------------------+

source/community/release_notes/ulmo/ulmo_rp.rst

@@ -145,6 +145,10 @@
         f"https://docs.openedx.org/projects/edx-credentials/{rtd_language}/{rtd_version}",
         None,
     ),
+    "authz": (
+        f"https://docs.openedx.org/projects/openedx-authz/{rtd_language}/{rtd_version}",
+        None,
+    ),
 }
 
 # Add any paths that contain templates here, relative to this directory.

source/community/release_notes/verawood/stay_up_to_date.rst

@@ -10,7 +10,8 @@ Add a Problem Bank to your course for randomization
     Content must be :ref:`published in a Library<Publish Library content>`
     before it can be used in a Course.
 
-    A course author must have at least the **Library User** role to reuse content.
+    A course author must have at least the **Library User** role to reuse content, *or*,
+    the library should be published with the **Allow Public Read** permission.
     See :ref:`Add users to Libraries` for more detail.
 
 #. From the Unit Page in a course outline, click on the Problem Bank tile. A