docs: added IMPORTANT comment for R&P about event

- Added a long comment describing how the new event data is tech debt. - Changed data name to "ManageStudentsPermissionData" to reflect these changes.
openedx · Sep 29, 2023 · f34982c · f34982c
1 parent 963ef4f
commit f34982c
Show file tree

Hide file tree

Showing 4 changed files with 93 additions and 32 deletions.
diff --git a/...er+course+staff+role+added+v1_schema.avsc → ...+students+permission+added+v1_schema.avsc b/...er+course+staff+role+added+v1_schema.avsc → ...+students+permission+added+v1_schema.avsc
@@ -6,13 +6,9 @@
     {
       "name": "course_staff_data",
       "type": {
-        "name": "CourseStaffData",
+        "name": "ManageStudentsPermissionData",
         "type": "record",
         "fields": [
-          {
-            "name": "course_key",
-            "type": "string"
-          },
           {
             "name": "user",
             "type": {
@@ -50,10 +46,30 @@
                 }
               ]
             }
+          },
+          {
+            "name": "permission",
+            "type": "string"
+          },
+          {
+            "name": "course_key",
+            "type": [
+              "null",
+              "string"
+            ],
+            "default": null
+          },
+          {
+            "name": "org",
+            "type": [
+              "null",
+              "string"
+            ],
+            "default": null
           }
         ]
       }
     }
   ],
-  "namespace": "org.openedx.learning.user.course.staff.role.added.v1"
+  "namespace": "org.openedx.learning.user.manage.students.permission.added.v1"
 }
diff --git a/...+course+staff+role+removed+v1_schema.avsc → ...tudents+permission+removed+v1_schema.avsc b/...+course+staff+role+removed+v1_schema.avsc → ...tudents+permission+removed+v1_schema.avsc
@@ -6,13 +6,9 @@
     {
       "name": "course_staff_data",
       "type": {
-        "name": "CourseStaffData",
+        "name": "ManageStudentsPermissionData",
         "type": "record",
         "fields": [
-          {
-            "name": "course_key",
-            "type": "string"
-          },
           {
             "name": "user",
             "type": {
@@ -50,10 +46,30 @@
                 }
               ]
             }
+          },
+          {
+            "name": "permission",
+            "type": "string"
+          },
+          {
+            "name": "course_key",
+            "type": [
+              "null",
+              "string"
+            ],
+            "default": null
+          },
+          {
+            "name": "org",
+            "type": [
+              "null",
+              "string"
+            ],
+            "default": null
           }
         ]
       }
     }
   ],
-  "namespace": "org.openedx.learning.user.course.staff.role.removed.v1"
+  "namespace": "org.openedx.learning.user.manage.students.permission.removed.v1"
 }
diff --git a/openedx_events/learning/data.py b/openedx_events/learning/data.py
@@ -299,14 +299,43 @@ class ProgramCertificateData:
 
 
 @attr.s(frozen=True)
-class CourseStaffData:
+class ManageStudentsPermissionData:
     """
-    Attributes defined for the Open edX Authentication function to Add Users to a role.
+    Attributes defined for the Open edX to represent users that can manage students within a course/org.
+
+    IMPORTANT:
+        edX currently uses roles, and only roles, to decide what kind of access a user has.
+
+        There is an ongoing project to replace this roles-only system with a system that uses roles that are
+        made up of permissions, which is being worked on in parallel with another project to emit events
+        whenever users are assigned any type of "Course Staff" role.
+
+        It's unclear what the state of this roles/permissions project will be the time the events project
+        is completed, so each project's respective teams will stay in touch with each other.
+
+        For now, we're making a best effort to publish this an event that will regard the permission(s)
+        we'd expect to "filter" for in the future (For more info, please check out this document:
+        https://docs.google.com/spreadsheets/d/1htsV0eWq5-y96DZ5A245ukfZ4_qeH0KjHVaOyfqD8OA/edit#gid=908503896)
+        and not for the roles we have now. Likely this/these permission(s) will be something like `manage_students`,
+        but we need to evaluate how this will align with some possible future roles such as `limited_staff` or `ccx`.
+
+        As such, the current plan is to do one of the following once the roles/permissions project's
+        feature branch is merged to master:
+            1. Modify this event to "filter" by the correct permissions once the
+            2. As a backup plan, make a new event if this proves too difficult.
+
+        Until either of these plans are executed, this comment under the IMPORTANT header should stay put.
 
     Arguments:
-        course_key (Course ID): identifier of the course where the user will have staff role assigned/removed
-        user (UserData): User who will have the "Course Staff" role assigned/removed
+        user (UserData): User who will have a role/permission assigned/removed.
+        permission (str): The permission the user is being assigned.
+        course_key (Course ID): identifier of the course where the user will have staff role assigned/removed.
+            A blank course_id implies org wide role.
+        org (str): identifier of the org where the user will have staff role assigned/removed.
+            A blank org is for global group based roles such as course creator (may be deprecated).
     """
 
-    course_key = attr.ib(type=str)
     user = attr.ib(type=UserData)
+    permission = attr.ib(type=str)
+    course_key = attr.ib(type=str, default=None)
+    org = attr.ib(type=str, default=None)
diff --git a/openedx_events/learning/signals.py b/openedx_events/learning/signals.py
@@ -13,7 +13,7 @@
     CohortData,
     CourseDiscussionConfigurationData,
     CourseEnrollmentData,
-    CourseStaffData,
+    ManageStudentsPermissionData,
     PersistentCourseGradeData,
     ProgramCertificateData,
     UserData,
@@ -198,24 +198,24 @@
     }
 )
 
-# .. event_type: org.openedx.learning.user.course.staff.role.added.v1
-# .. event_name: COURSE_STAFF_ROLE_ADDED
-# .. event_description: Emitted when the "Course Staff" role is added to a user.
-# .. event_data: CourseStaffData
-COURSE_STAFF_ROLE_ADDED = OpenEdxPublicSignal(
-    event_type="org.openedx.learning.user.course.staff.role.added.v1",
+# .. event_type: org.openedx.learning.user.manage.students.permission.added.v1
+# .. event_name: MANAGE_STUDENTS_PERMISSION_ADDED
+# .. event_description: Emitted when permission to manage students within a course is given to a user.
+# .. event_data: ManageStudentsPermissionData
+MANAGE_STUDENTS_PERMISSION_ADDED = OpenEdxPublicSignal(
+    event_type="org.openedx.learning.user.manage.students.permission.added.v1",
     data={
-        "course_staff_data": CourseStaffData,
+        "course_staff_data": ManageStudentsPermissionData,
     }
 )
 
-# .. event_type: org.openedx.learning.user.course.staff.role.removed.v1
-# .. event_name: COURSE_STAFF_ROLE_REMOVED
-# .. event_description: Emitted when the "Course Staff" role is removed from a user.
-# .. event_data: CourseStaffData
-COURSE_STAFF_ROLE_REMOVED = OpenEdxPublicSignal(
-    event_type="org.openedx.learning.user.course.staff.role.removed.v1",
+# .. event_type: org.openedx.learning.user.manage.students.permission.removed.v1
+# .. event_name: MANAGE_STUDENTS_PERMISSION_REMOVED
+# .. event_description: Emitted when permission to manage students within a course is removed from a user.
+# .. event_data: ManageStudentsPermissionData
+MANAGE_STUDENTS_PERMISSION_REMOVED = OpenEdxPublicSignal(
+    event_type="org.openedx.learning.user.manage.students.permission.removed.v1",
     data={
-        "course_staff_data": CourseStaffData,
+        "course_staff_data": ManageStudentsPermissionData,
     }
 )