From 57a98a263b0bdb6c25706ff512b912ef55af3660 Mon Sep 17 00:00:00 2001 From: Emad Rad Date: Sat, 9 Nov 2024 11:47:34 +0330 Subject: [PATCH 1/5] chore: trailing whitespace removed --- README.rst | 3 - .../oep-0049-django-app-patterns.rst | 2 +- .../oep-0066-bp-authorization.rst | 188 +++++++++--------- .../oep-0067-bp-tools-and-technology.rst | 8 +- .../decisions/frontend/0006-codecov.rst | 2 +- .../decisions/frontend/0007-bundle-size.rst | 10 +- .../decisions/frontend/0008-typescript.rst | 8 +- .../decisions/frontend/0009-renovate.rst | 4 +- .../processes/oep-0014-proc-archive-repos.rst | 4 +- oeps/processes/oep-0021-proc-deprecation.rst | 2 +- ...1-use-backstage-to-support-maintainers.rst | 2 +- oeps/processes/oep-0057-proc-core-product.rst | 12 +- .../oep-0063-proc-toc-resolution-request.rst | 26 +-- 13 files changed, 134 insertions(+), 137 deletions(-) diff --git a/README.rst b/README.rst index e11943832..3885f8459 100644 --- a/README.rst +++ b/README.rst @@ -43,8 +43,6 @@ all proposed changes and additions on `pull requests`_. .. _ReStructured Text (RST): https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html .. _pull requests: https://docs.openedx.org/en/latest/developers/quickstarts/first_openedx_pr.html - - Testing Locally *************** @@ -56,7 +54,6 @@ Next run the following commands:: pip install sphinx # it may fail for non-obvious reasons without this make requirements - make html Common Warnings diff --git a/oeps/best-practices/oep-0049-django-app-patterns.rst b/oeps/best-practices/oep-0049-django-app-patterns.rst index b91f10eb0..32397fa83 100644 --- a/oeps/best-practices/oep-0049-django-app-patterns.rst +++ b/oeps/best-practices/oep-0049-django-app-patterns.rst @@ -204,7 +204,7 @@ Example from enum import Enum from attrs import field, frozen, validators - + class ProgramStatus(Enum): ACTIVE = "active" RETIRED = "retired" diff --git a/oeps/best-practices/oep-0066-bp-authorization.rst b/oeps/best-practices/oep-0066-bp-authorization.rst index 7af85b07c..733429f38 100644 --- a/oeps/best-practices/oep-0066-bp-authorization.rst +++ b/oeps/best-practices/oep-0066-bp-authorization.rst @@ -11,7 +11,7 @@ OEP-66: User Authorization * - Last Modified - 2023-10-20 * - Authors - - Hilary Sinkoff (hsinkoff@2u.com), Jeremy Bowman (jbowman@edx.org) + - Hilary Sinkoff (hsinkoff@2u.com), Jeremy Bowman (jbowman@edx.org) * - Arbiter - Feanil Patel (feanil@axim.org) * - Status @@ -25,15 +25,15 @@ OEP-66: User Authorization * - Replaces - :doc:`/archived/oep-0009-bp-permissions` * - References - - + - * :doc:`/architectural-decisions/oep-0004-arch-oauth-scopes` * :doc:`oep-0042-bp-authentication` - + Summary ******* -There are a variety of manners in which authorization is handled within the Open edX ecosystem. -The goal of OEP-66 is to provide best practices that should be used with each of the +There are a variety of manners in which authorization is handled within the Open edX ecosystem. +The goal of OEP-66 is to provide best practices that should be used with each of the systems/protocols and outline the systems/protocols that are currently in use. Motivation @@ -64,12 +64,12 @@ particular role, etc. This has a few drawbacks: Systems/Protocols Overview Motivation ------------------------------------- -There are currently multiple systems/protocols that control authorization. -Determining which combination of systems/protocols are responsible for granting access -is a complex task made more complex by the lack of -unified documentation on the systems/protocols. This OEP aims to compile existing -knowledge and documentation into a central document that will give an overview of each -system/protocol. The aim is not to be the only source of information for each system/protocol, +There are currently multiple systems/protocols that control authorization. +Determining which combination of systems/protocols are responsible for granting access +is a complex task made more complex by the lack of +unified documentation on the systems/protocols. This OEP aims to compile existing +knowledge and documentation into a central document that will give an overview of each +system/protocol. The aim is not to be the only source of information for each system/protocol, but rather a starting point when learning about authorization within the Open edX codebase. Defined Terms @@ -81,7 +81,7 @@ Authorization (Authz) Authorization is the granting of permission of a certain user to perform specific operations in an application. A user can also delegate an application to be authorized to perform operations on their behalf without being logged in or authenticated, which is the basis of OAuth. .. note:: - The definition of authorization found here is the same as that found in + The definition of authorization found here is the same as that found in :doc:`OEP 42 `. Credit for this definition belongs to the authors of OEP-42; Robert Raposa, Nimisha Asthagiri, and Julia Eskew. @@ -92,17 +92,17 @@ Authentication is the verification of the identity of a user, which typically in .. note:: - Authentication is out of scope of this OEP. + Authentication is out of scope of this OEP. The definition is included here to clarify the difference between it and Authorization. The definition comes from :doc:`OEP 42 `. Credit for this definition belongs to the authors of OEP-42; Robert Raposa, Nimisha Asthagiri, and Julia Eskew. RBAC ---- -Role Based Access Control. A system in which roles are assigned to a user +Role Based Access Control. A system in which roles are assigned to a user in order to grant that user permission to perform specific operations. -There are multiple RBAC implementations in use within the Open edX codebase, +There are multiple RBAC implementations in use within the Open edX codebase, including, but not limited to, `edx-rbac`_ and `student_courseaccessrole`_. The implementations will be described in detail below. @@ -111,15 +111,15 @@ The implementations will be described in detail below. Explicit Role ------------- -A role that is specifically assigned to a user with +A role that is specifically assigned to a user with the intent of providing the user permission to perform specific operations. Implicit Role ------------- -A "role" that is understood to belong to a user based -on data that is not role assignment data. +A "role" that is understood to belong to a user based +on data that is not role assignment data. -Implicit roles grant users permissions, but are not specifically assigned +Implicit roles grant users permissions, but are not specifically assigned to a user. System-wide Role @@ -128,8 +128,8 @@ A role that can be used across all Open edX Software. Super User ---------- -A service specific role that exists only for the specified service and -grants a high level of access to the service (for example access to Django Admin +A service specific role that exists only for the specified service and +grants a high level of access to the service (for example access to Django Admin or read-write access for all database models). Best Practices @@ -182,20 +182,20 @@ can help give context for the details: Extending Permission Checks =========================== -While the +While the `Django authorization API`_ is quite flexible, many Django developers have not really utilized it because the default authentication backend that comes with Django lacks support for object-level permissions and requires the addition of per-user database records for even the most trivial permission checks. Fortunately, Django supports custom authentication backends, and -checks each one that's in use when making authorization checks. +checks each one that's in use when making authorization checks. The backend which we currently recommend for use in defining new permission checks is -`bridgekeeper`_. +`bridgekeeper`_. `bridgekeeper`_ is "heavily inspired by `django-rules`_". It allows the creation of new permissions by mapping -the permission name to a function which implements the permission check. It also allows permission checking by +the permission name to a function which implements the permission check. It also allows permission checking by QuerySet. Django apps which are @@ -206,7 +206,7 @@ loaded, as described in the documentation. For example: .. _bridgekeeper: https://bridgekeeper.readthedocs.io/en/latest/index.html .. _django-rules: https://github.com/dfunckt/django-rules -`This code grants the my_app.view_report permission to users that return true from the new +`This code grants the my_app.view_report permission to users that return true from the new is_report_owner function or the imported is_superuser function.` .. code-block:: python @@ -225,7 +225,7 @@ This allows permissions to be named and implemented in one place, without requiring any additional database configuration. Note that reusable Django applications should not automatically register implementations of their permissions, as the actual services using them may need to implement their -own rules for them. +own rules for them. Note that although the optional second argument to ``User.has_perm()`` is often a model instance, it can technically be any Python object which contains @@ -239,7 +239,7 @@ Django REST Framework When using Django REST Framework (DRF) to build a REST API, note that it has object permissions and query filtering mechanisms which are designed to be compatible with Django's authorization API. This means they also work well with the -``bridgekeeper`` authentication backend described above. +``bridgekeeper`` authentication backend described above. You can `set the permissions policy`_ to a class such as `DjangoObjectPermissions`_ @@ -269,7 +269,7 @@ changed if desired by creating a subclass, for example: If additional information about the session is needed beyond the user's identity in order to make a permission decision (for example, if an action should only be allowed if the client has been granted a particular OAuth -scope, as outlined in :doc:`OEP 4 `), +scope, as outlined in :doc:`OEP 4 `), then a custom `BasePermission`_ subclass can be implemented which both consults the Django authorization API and makes the necessary checks against the session or other properties of the request @@ -308,14 +308,14 @@ could be used by default for all view classes which don't override it. Systems/Protocols Overview ************************** -The following systems/protocols are currently used in the Open edX ecosystem -to grant users different levels of access. Each system/protocol is used in different -ways. A user's authz level is determined based on a combination of these systems/protocols. -It is important to note that it is the interplay of these systems/protocols that -determines whether a user has permissions for a given operation, not necessarily a single +The following systems/protocols are currently used in the Open edX ecosystem +to grant users different levels of access. Each system/protocol is used in different +ways. A user's authz level is determined based on a combination of these systems/protocols. +It is important to note that it is the interplay of these systems/protocols that +determines whether a user has permissions for a given operation, not necessarily a single system. -Basic information about each system/protocol is included in the diagram and data tables. +Basic information about each system/protocol is included in the diagram and data tables. More in-depth information is included in the sections below the diagrams. Open edX Auth Overview Diagram @@ -364,26 +364,26 @@ There are two ways in which the Django auth_permissions can be used to grant acc * Users can be granted model permissions based on the database models. * Users can be assigned to groups which can be granted model permissions based on the database models. -Django Admin auth_permissions grants permissions to users or groups, but does not -control whether the user is able to login to a service (authn) or access a service through other permissions -(i.e. an implicit student role). +Django Admin auth_permissions grants permissions to users or groups, but does not +control whether the user is able to login to a service (authn) or access a service through other permissions +(i.e. an implicit student role). In this way, it can grant permissions to a user that they will not be able to use. -auth_permission users and groups are assigned through the Django Admin Dashboard. Each -service can have its own Django Admin Dashboard. In the Open edX software, the LMS Django Admin Dashboard +auth_permission users and groups are assigned through the Django Admin Dashboard. Each +service can have its own Django Admin Dashboard. In the Open edX software, the LMS Django Admin Dashboard will be used to control (most) user and group permissions. student_courseaccessrole ------------------------ -Explicit roles are assigned to users, generally on a course level basis. +Explicit roles are assigned to users, generally on a course level basis. The roles are hardcoded strings that can be granted in the LMS or CMS. -In addition to granting the roles in the UI, it is possible to assign -the roles through the LMS Django Admin Dashboard. +In addition to granting the roles in the UI, it is possible to assign +the roles through the LMS Django Admin Dashboard. -Each role assignment will generate one row in the database table. The values -in the row will determine if the user is granted access for a single course, all +Each role assignment will generate one row in the database table. The values +in the row will determine if the user is granted access for a single course, all courses in the org, or all courses in the instance. * If the course_id is not nil, the role grants permissions on the course level. @@ -393,37 +393,37 @@ courses in the org, or all courses in the instance. django_comment_client_role -------------------------- -Explicit roles are assigned to users on a course level basis. +Explicit roles are assigned to users on a course level basis. -Each role is made up of a combination of permissions stored in the database. +Each role is made up of a combination of permissions stored in the database. -These roles require that the user already be enrolled in the course +These roles require that the user already be enrolled in the course (have an enrollment, audit or verified). -Roles are assigned through the LMS in the same place in the UI as the student_courseaccessrole roles. +Roles are assigned through the LMS in the same place in the UI as the student_courseaccessrole roles. They can also be granted in the LMS Django Admin Dashboard. -Access is granted through a combination of checking a user's role and checking if a user has a specified permission. +Access is granted through a combination of checking a user's role and checking if a user has a specified permission. In some situations, the code also checks if a user has a combination (and or or) of permissions to grant access. course_roles_role (Proposed Service) ------------------------------------ .. note:: - Code related to the course_role schema is in progress. + Code related to the course_role schema is in progress. This section describes the intended usage, but not all portions have been implemented at this time. The code is not being used in production at this time. - + Please see `platform-roadmap issue 246 `_ for more information about the status of the project. -Explicit course level roles are assigned to users. The roles grant access on the course level, -but can also be assigned organization or instance wide. +Explicit course level roles are assigned to users. The roles grant access on the course level, +but can also be assigned organization or instance wide. -**Permissions:** +**Permissions:** -Each role is a combination of the permissions found in the course_roles_permission database table. -The permissions in course_roles_permission are used to determine authorization (access) within the code. As a result, -new roles can be added to the database, connected to existing permissions, and utilized in the system +Each role is a combination of the permissions found in the course_roles_permission database table. +The permissions in course_roles_permission are used to determine authorization (access) within the code. As a result, +new roles can be added to the database, connected to existing permissions, and utilized in the system with minimal effort. **Role Assignment** @@ -434,21 +434,21 @@ If needed, additional UI locations can be added at a later date. When a course_roles_role is created, a course_roles_roleservice database row (or rows) should also be created that link the role to the UI service where the role should be assignable to users. The course_roles_role list will be filtered by course_roles_roleservice values to determine which roles to show in each UI role assignment page (Course Team, Membership, Course_Roles). -Each role assignment will generate one row in the course_roles_userrole database table. The values -in the row will determine if the user is granted access for a single course, all +Each role assignment will generate one row in the course_roles_userrole database table. The values +in the row will determine if the user is granted access for a single course, all courses in the org, or all courses in the instance. * If a userrole is assigned to a course, it grants access based on the related permissions to that course. * If a userrole is assigned on an organization wide level, it grants access based on the related permissions to all courses that belong to the organization. * If a userrole is assigned on an instance wide level, it grants access based on the related permissions to all courses that belong to the instance. -The course_roles_userrole database table utilizes foreign keys to user, role, course (CourseOverview), and organization. It is not +The course_roles_userrole database table utilizes foreign keys to user, role, course (CourseOverview), and organization. It is not possible to assign a course_roles_userrole on an object that is not a course (does not have a CourseOverview) in the database. .. note:: - Once the proposed course_roles architecture is created, the next planned step is to migrate - existing student_courseaccessrole roles to the course_roles schema and deprecate the student_courseaccessrole roles. - The comment_client roles are also being considered for migration to course_roles, but are considered lower + Once the proposed course_roles architecture is created, the next planned step is to migrate + existing student_courseaccessrole roles to the course_roles schema and deprecate the student_courseaccessrole roles. + The comment_client roles are also being considered for migration to course_roles, but are considered lower priority because they are already based upon permissions. .. image:: oep-0066/Open_edX_Course_Roles_Proposal.png @@ -463,49 +463,49 @@ possible to assign a course_roles_userrole on an object that is not a course (do edx-rbac -------- -Permission is granted on a Feature. +Permission is granted on a Feature. -edx-rbac is a protocol that can be implemented by any feature, but each +edx-rbac is a protocol that can be implemented by any feature, but each feature that implements it would need to set up its own implementation. It allows for creating feature specific roles with feature specific permissions. -The feature specific roles can be accessed by other -features which can choose to use or ignore this data point. +The feature specific roles can be accessed by other +features which can choose to use or ignore this data point. -The feature specific roles are stored on the jwt token. This mixes authz into an -authn data point, but is an accepted way to implement feature specific roles and permissions. -It is advisable to be very careful regarding the jwt token header limits if adding a new feature specific +The feature specific roles are stored on the jwt token. This mixes authz into an +authn data point, but is an accepted way to implement feature specific roles and permissions. +It is advisable to be very careful regarding the jwt token header limits if adding a new feature specific set of roles using this implementation path. content_libraries_contentlibrarypermission ------------------------------------------ -Permission is granted on a Feature, in this case Content Library. +Permission is granted on a Feature, in this case Content Library. -Permission is assigned in the CMS exclusively for providing explicit permission to -view or edit a library in the CMS. +Permission is assigned in the CMS exclusively for providing explicit permission to +view or edit a library in the CMS. -It grants access on a library by library basis and is used for v2 of content libraries -in the CMS. +It grants access on a library by library basis and is used for v2 of content libraries +in the CMS. .. note:: - v1 libraries (deprecated) granted access to libraries on a course by course basis + v1 libraries (deprecated) granted access to libraries on a course by course basis and was controlled by student_courseaccessrole. Student/Learner --------------- -student/learner is an implicit role. +student/learner is an implicit role. -It is not currently controlled by a system/protocol -whose primary focus is authorization. +It is not currently controlled by a system/protocol +whose primary focus is authorization. System-wide Roles ----------------- -System-wide roles are configurable and can differ between different Open edX instances. This -means that different instances can have different system-wide roles. +System-wide roles are configurable and can differ between different Open edX instances. This +means that different instances can have different system-wide roles. System-wide user-roles (user assignments to a specific system-wide role) are -stored in a central user service (currently LMS) and communicated via JWT Tokens. +stored in a central user service (currently LMS) and communicated via JWT Tokens. If a feature/service utilizes a system-wide role, the feature/service enforces the roles in its own codebase. @@ -518,21 +518,21 @@ Example AuthZ User Access Flows .. image:: oep-0066/Open_edX_Authorization_User_Flows.png :alt: A diagram that attempts to show different ways in which users can be granted elevated access. -Users can be granted elevated access via different means (system-wide roles, edx-rbac, student_courseaccessroles, etc). +Users can be granted elevated access via different means (system-wide roles, edx-rbac, student_courseaccessroles, etc). This diagram illustrates some, but not all, ways a user can be granted elevated access. -User 1 is assigned to User Group 1 and User Group 2. -Being in User Group 1 grants the user System-wide Role A and System-wide Role B, -which in turn each grant a specific permission set or sets for a service. -Being in User Group 2 grants access to System-wide Role C +User 1 is assigned to User Group 1 and User Group 2. +Being in User Group 1 grants the user System-wide Role A and System-wide Role B, +which in turn each grant a specific permission set or sets for a service. +Being in User Group 2 grants access to System-wide Role C which grants access to a service permission set. User 2 is assigned to User Group 2. Being in User Group 2 grants access to System-wide Role C which grants access to a service permission set. -User 2 is also directly assigned System-wide Role D +User 2 is also directly assigned System-wide Role D which grants access to a different service permission set. -User 2 is also assigned Service/Feature Role A +User 2 is also assigned Service/Feature Role A which grants access to a service permission set. User 3 is assigned to Service/Feature Role A and Service/Feature Role B. @@ -552,8 +552,8 @@ As demonstrated by the above flows: * a service permission set can be associated with multiple system-wide roles and/or service/feature roles .. note:: - Not illustrated in the diagram or user flows is the fact that multiple services can use the same - system-wide roles to grant different permission sets. + Not illustrated in the diagram or user flows is the fact that multiple services can use the same + system-wide roles to grant different permission sets. The permission sets do not persist between services, but the system-wide roles are available globally. Historical Systems/Protocols @@ -562,7 +562,7 @@ Historical Systems/Protocols This is a listing of the systems/protocols that have been used historically, but have since been phased out. This list should include a link to any ADRs or documents that reflect why these changes were made. -* `rules`_ was previously the preferred method for extending permission checks. +* `rules`_ was previously the preferred method for extending permission checks. * `ADR for adding django-rules `_ * `ADR for switching to bridgekeeper `_ @@ -577,7 +577,7 @@ References `django-rules `_ -`bridgekeeper `_ +`bridgekeeper `_ Change History ************** diff --git a/oeps/best-practices/oep-0067-bp-tools-and-technology.rst b/oeps/best-practices/oep-0067-bp-tools-and-technology.rst index d36003a66..0dcf6172f 100644 --- a/oeps/best-practices/oep-0067-bp-tools-and-technology.rst +++ b/oeps/best-practices/oep-0067-bp-tools-and-technology.rst @@ -68,7 +68,7 @@ This technology is not specific to frontend or backend code. **Rationale**: It is important to measure the amount of code covered by our automated test suites. By striving for a high level of test coverage, we can - reduce the number of bugs that can only be found via manual testing, + reduce the number of bugs that can only be found via manual testing, and by using codecov to run coverage in CI, contributors are automatically reminded to include tests for any new code. @@ -84,12 +84,12 @@ This technology is not specific to frontend or backend code. Frontend Technology Selection ============================= -.. note:: +.. note:: The phrase “frontend” is used to mean any part of the platform that is shown to users. This encompasses views rendered in Python on the server, interactive interfaces written using JavaScript, and CSS styling. - + .. _Use React: #. **Use React** @@ -250,7 +250,7 @@ Frontend Technology Selection **Rationale**: It is important for users of the Open edX platform that we deliver reasonably sized JavaScript bundles. This provides faster load times to all users, - and is vital for users with low bandwidth and/or metered connections. To ensure we + and is vital for users with low bandwidth and/or metered connections. To ensure we don't unintentionally increase the size of our JavaScript bundles, we utilize BundleWatch for automated bundle size monitoring. diff --git a/oeps/best-practices/oep-0067/decisions/frontend/0006-codecov.rst b/oeps/best-practices/oep-0067/decisions/frontend/0006-codecov.rst index 4c230bec8..70251ccb4 100644 --- a/oeps/best-practices/oep-0067/decisions/frontend/0006-codecov.rst +++ b/oeps/best-practices/oep-0067/decisions/frontend/0006-codecov.rst @@ -27,6 +27,6 @@ Rejected Alternatives Coveralls ========= -Coveralls has been historically used for tracking coverage but the service has become less reliable over time and the larger python has moved away from it. +Coveralls has been historically used for tracking coverage but the service has become less reliable over time and the larger python has moved away from it. .. _Codecov: https://about.codecov.io/ \ No newline at end of file diff --git a/oeps/best-practices/oep-0067/decisions/frontend/0007-bundle-size.rst b/oeps/best-practices/oep-0067/decisions/frontend/0007-bundle-size.rst index f566ff6d6..b27855fad 100644 --- a/oeps/best-practices/oep-0067/decisions/frontend/0007-bundle-size.rst +++ b/oeps/best-practices/oep-0067/decisions/frontend/0007-bundle-size.rst @@ -10,11 +10,11 @@ Context ******* It is important for users of the Open edX platform that we deliver reasonably sized JavaScript bundles. This provides -faster load times to all users, and is vital for users with low bandwidth and/or metered connections. +faster load times to all users, and is vital for users with low bandwidth and/or metered connections. It is currently possible to manually monitor bundle size information by utilizing webpack configurations provided by frontend-build, but this functionality is not very discoverable. Given the "hidden" nature of this functionality, it is -very possible for changes that increase bundle size to be missed in the PR review process. +very possible for changes that increase bundle size to be missed in the PR review process. The increased visibility provided by automated bundle size monitoring will ensure we don't unintentionally increase the size of our JavaScript bundles, as well as encourage maintainers to adopt best practices such as `code splitting`_. @@ -28,7 +28,7 @@ decide if this CI check will be blocking or informative on a repo-by-repo basis. BundleWatch =========== -`BundleWatch`_ is solely focused on ensuring bundle sizes stay under control. It is actively maintained and used by popular projects such as `bootstrap`_. +`BundleWatch`_ is solely focused on ensuring bundle sizes stay under control. It is actively maintained and used by popular projects such as `bootstrap`_. Consequence *********** @@ -41,13 +41,13 @@ Rejected Alternatives ********************* 1. **Code Checks** - + `Code Checks`_ is a pluggable framework for automated code review. It provides more than just bundle size monitoring, presenting us with an opportunity to rethink our current CI workflows. For example, Code Checks provides test coverage monitoring, which would allow us to re-evaluate the choice to use CodeCov as documented in :doc:`0006-codecov`. - + While this additional functionality is potentially desirable, moving forward with a single purpose tool (`BundleWatch`_) provides us the functionality we need with minimal changes to our current CI workflows. diff --git a/oeps/best-practices/oep-0067/decisions/frontend/0008-typescript.rst b/oeps/best-practices/oep-0067/decisions/frontend/0008-typescript.rst index 260dc86c9..fb7f2f1cf 100644 --- a/oeps/best-practices/oep-0067/decisions/frontend/0008-typescript.rst +++ b/oeps/best-practices/oep-0067/decisions/frontend/0008-typescript.rst @@ -9,8 +9,8 @@ Accepted Context ******* -As documented in :doc:`OEP-0011-0004 <0004-js-ecma>`, the Open edX community has previously -:ref:`decided against adopting TypeScript `. In the time +As documented in :doc:`OEP-0011-0004 <0004-js-ecma>`, the Open edX community has previously +:ref:`decided against adopting TypeScript `. In the time since that decision was made, TypeScript has grown to be quite popular and commonplace for JavaScript developers. This has led to more discussion within the community about the `pros and cons of adopting TypeScript`_. @@ -33,7 +33,7 @@ Rejected Alternatives ********************* 1. **Continue without TypeScript** - + It is possible to use other tools to add some of the functionality TypeScript provides to JavaScript code. However, considering the main point of opposition to TypeScript adoption was keeping a low barrier of entry for frontend developers, this could be counterproductive. @@ -42,6 +42,6 @@ Rejected Alternatives It would be possible to convert all JavaScript throughout the Open edX project (or any given repository within the project) to TypeScript. It is not clear what the benefit of doing so would - be. + be. .. _pros and cons of adopting TypeScript: https://github.com/openedx/paragon/discussions/1186 diff --git a/oeps/best-practices/oep-0067/decisions/frontend/0009-renovate.rst b/oeps/best-practices/oep-0067/decisions/frontend/0009-renovate.rst index 47b9f5d7f..eef283829 100644 --- a/oeps/best-practices/oep-0067/decisions/frontend/0009-renovate.rst +++ b/oeps/best-practices/oep-0067/decisions/frontend/0009-renovate.rst @@ -48,9 +48,9 @@ Rejected Alternatives for identifying the root cause of a test failure but resulted in a pretty high volume of PRs that needed to be reviewed (especially in repositories which normally don't need to be updated very often). Renovate has - `configuration options to set the frequency of checking for new dependency + `configuration options to set the frequency of checking for new dependency releases `_, - and to allow related packages to be `updated in the same pull + and to allow related packages to be `updated in the same pull request `_. This may delay notification of security patch releases or make it harder to identify the exact cause of a test failure, but also makes it less likely that the PRs will be diff --git a/oeps/processes/oep-0014-proc-archive-repos.rst b/oeps/processes/oep-0014-proc-archive-repos.rst index b09b69dce..8c2b3b37a 100644 --- a/oeps/processes/oep-0014-proc-archive-repos.rst +++ b/oeps/processes/oep-0014-proc-archive-repos.rst @@ -89,9 +89,9 @@ These steps should be followed for all repos within the Open edX organization (f - Move the repository to the openedx-unsupported organization - Remove references to the repository from the ``openedx-translations`` `repository `_ - + - The entry in the ``extract-translation-source-files`` `workflow `_ - + - The subdirectory in the ``translations`` `directory `_ - Create an ``axim-engineering`` `request `_ to remove the repository resource from the ``openedx-translations`` project on Transifex diff --git a/oeps/processes/oep-0021-proc-deprecation.rst b/oeps/processes/oep-0021-proc-deprecation.rst index a28cd53cb..6cac0e80d 100644 --- a/oeps/processes/oep-0021-proc-deprecation.rst +++ b/oeps/processes/oep-0021-proc-deprecation.rst @@ -317,7 +317,7 @@ The coordinator is responsible for: When you are ready to coordinate the ticket, post a comment on the GitHub issue saying you're doing so, and mark yourself as the GitHub -issue's owner. This can be done even if you don't have write access to +issue's owner. This can be done even if you don't have write access to the ticket by making a comment on the ticket that says ``assign me``. .. note:: diff --git a/oeps/processes/oep-0055/decisions/0001-use-backstage-to-support-maintainers.rst b/oeps/processes/oep-0055/decisions/0001-use-backstage-to-support-maintainers.rst index 39b13f528..b5e2d2d04 100644 --- a/oeps/processes/oep-0055/decisions/0001-use-backstage-to-support-maintainers.rst +++ b/oeps/processes/oep-0055/decisions/0001-use-backstage-to-support-maintainers.rst @@ -123,7 +123,7 @@ References # names that might be interested in changes to the architecture of this # component. openedx.org/arch-interest-groups: "feanil" - # (Optional) We use the below annotation to indicate whether or not this + # (Optional) We use the below annotation to indicate whether or not this # repository should be tagged for openedx releases and which branch is tagged. openedx.org/release: "main" spec: diff --git a/oeps/processes/oep-0057-proc-core-product.rst b/oeps/processes/oep-0057-proc-core-product.rst index 9a589273b..4ca8a3897 100644 --- a/oeps/processes/oep-0057-proc-core-product.rst +++ b/oeps/processes/oep-0057-proc-core-product.rst @@ -86,7 +86,7 @@ Product Narrative The *Product Narrative* is defined as the high-level vision statement for the Open edX project. It succinctly articulates the value proposition and impact of the project, the features which differentiate it, and the values and -characteristics that position it as a market-leading solution. +characteristics that position it as a market-leading solution. Ongoing work to define the Product Narrative and subsequent deliverables can be tracked on the `Product Narrative wiki space`_. @@ -114,7 +114,7 @@ questions such as: Product, and why? * What is the spectrum of alternatives if a developed feature doesn't align with - the Core Product? + the Core Product? Ongoing work to define the Core Product and subsequent deliverables can be tracked on the `Core Product Offering wiki space`_. @@ -245,7 +245,7 @@ the highest impact parts of the project, as determined by a broad cross-section of the community itself. It will be clearer to the community which portions of the release they can expect support on, and which portions will have little to no support. Those components residing outside of the Core Product's Bundled -Extensions will not be a priority of the project's product strategy. +Extensions will not be a priority of the project's product strategy. The Core Product will be the focus of the project's product strategy; the project's various working groups are expected to prioritize support of the Core @@ -273,7 +273,7 @@ A clearly defined Core Product will assist product managers conducting market research to more easily identify feature gaps and parity analyses. They can ask questions such as: Do the highest impact features of the project adequately meet user needs? Where are they weak? How can we best invest to address those -weaknesses? +weaknesses? Marketing and Growth Efforts ============================ @@ -297,7 +297,7 @@ Notes There is desire in the Open edX community to refactor some or all of these features to be Bundled Extensions, which would reduce the size of the Kernel and bring it closer to our conceptions of an Ideal Kernel. - + The diagram of the Product Offerings and what they contain in the text represents a simplified version of what the Product Offerings are, and how they interact. A more full version of this visual can be seen below @@ -341,7 +341,7 @@ Notes .. _Richie: https://richie.education/ -.. _FUN MOOC: https://www.fun-mooc.fr/en/ +.. _FUN MOOC: https://www.fun-mooc.fr/en/ .. _OEP-10: https://open-edx-proposals.readthedocs.io/en/latest/processes/oep-0010-proc-openedx-releases.html diff --git a/oeps/processes/oep-0063-proc-toc-resolution-request.rst b/oeps/processes/oep-0063-proc-toc-resolution-request.rst index b8db7fe29..fce85177d 100644 --- a/oeps/processes/oep-0063-proc-toc-resolution-request.rst +++ b/oeps/processes/oep-0063-proc-toc-resolution-request.rst @@ -32,9 +32,9 @@ Abstract The Technical Oversight Committee (TOC) is meant to be a resource for the Open edX project. Thus it is important that there are clear lines of communication between the TOC and Open edX community. The purpose of this OEP is to establish and define those lines of communication. -The TOC aims to empower the project's contributors to make decisions. The person closest to the work will often know best, and empowered contributors face less friction. +The TOC aims to empower the project's contributors to make decisions. The person closest to the work will often know best, and empowered contributors face less friction. -However, some of the topics can be complex, such as making changes which will have long-lasting repercussions or when there is no consensus on a topic within the community. In this OEP, the TOC defines a process for community members to bring up topics to the committee's attention, and request its support on the matter. The TOC responds through the adoption of resolutions, for example intervening on the discussion or taking a decision about a proposal. +However, some of the topics can be complex, such as making changes which will have long-lasting repercussions or when there is no consensus on a topic within the community. In this OEP, the TOC defines a process for community members to bring up topics to the committee's attention, and request its support on the matter. The TOC responds through the adoption of resolutions, for example intervening on the discussion or taking a decision about a proposal. Motivation ********** @@ -47,13 +47,13 @@ Guidelines From the `TOC meeting notes `_: *The TOC should not operate “in the weeds.” We don’t have the time to be involved day-to-day technical decisions, and those closest to the work will make the best decisions. The TOC should not act as a “stage gate.” We should not create friction for contributors unnecessarily, but should:* - + - *Guide the project toward shared goals* - *Help refine and improve plans and designs* - *Prevent the project from making bad decisions that are hard to reverse.* - + *The TOC should weigh in:* - + - *on “one-way-doors,” decisions that are hard to reverse, where choices are mutually exclusive* - *when the community is having difficulty reaching consensus* - *when an important decision is being deferred and not making a call is causing friction* @@ -72,8 +72,8 @@ Step-by-step - How to Submit a Resolution Request - After public review, post a formal Resolution Request to the TOC, by opening a `github ticket `_. Mention the `TOC chair `_ in the request to make sure they get notified. See the format below. - Notify the participants of the public discussions that you have created the TOC Resolution Request, by posting a link to it in the discussion threads. - Core contributors and/or TOC members supporting the Resolution Request reply in the thread to say so. -- If the requirements are met, the TOC will schedule the topic for a future meeting. -- If the Resolution Request contains a suggested decision, the TOC can choose to accept the suggested decision, with or without changes, or to refuse it. +- If the requirements are met, the TOC will schedule the topic for a future meeting. +- If the Resolution Request contains a suggested decision, the TOC can choose to accept the suggested decision, with or without changes, or to refuse it. - The adopted Resolution is communicated as a reply to the github ticket, with a comment to explain it. Resolution Request - Github Ticket Template @@ -82,17 +82,17 @@ Resolution Request - Github Ticket Template .. code-block:: none Subj: TOC Resolution Request - [Title] - + --------------------- - + ## [Title] - - ## Summary + + ## Summary [Prior discussion of this topic (with links)] - + ## Rationale for involving the TOC [Why this topic would benefit from the TOC involvement] - + ## Resolution requested [The precise description of the request to the TOC, optionally including a specific decision to take if applicable. Note that the TOC doesn't have to take exactly that decision, it can modify it, or refuse it.] From 69fd5da88b267bfa5f5568d3bee8415d10ba9a22 Mon Sep 17 00:00:00 2001 From: Emad Rad Date: Sat, 9 Nov 2024 11:47:59 +0330 Subject: [PATCH 2/5] chore: code block added for better readability --- README.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 3885f8459..4fda01336 100644 --- a/README.rst +++ b/README.rst @@ -50,7 +50,9 @@ Before you make a pull request with your proposed changes, please try to visuall To test locally in a Python virtual env, you will first need to install `GraphViz `_ On a Mac, this can be done via ``brew install graphviz``; on Ubuntu, use ``sudo apt install graphviz``; on Red Hat variants use ``sudo dnf install graphviz``. -Next run the following commands:: +Next, run the following commands + +.. code-block:: bash pip install sphinx # it may fail for non-obvious reasons without this make requirements @@ -64,7 +66,9 @@ Document isn't Included in any toctree If you have some documents that you only reference via ``:doc:`` or ``:ref:`` tags you may get this error. If there is no table of contents that the files obviously belong in, an easy way to fix this error is to put the -documents in a hidden toctree near where they are referenced:: +documents in a hidden toctree near where they are referenced: + +.. code-block:: rst .. toctree:: :hidden: From 32f866af90ec91784ed57cb1f8e0dcb6fc24a02d Mon Sep 17 00:00:00 2001 From: Emad Rad Date: Sat, 9 Nov 2024 11:49:35 +0330 Subject: [PATCH 3/5] fix: heading style --- oeps/best-practices/oep-0017-bp-feature-toggles.rst | 2 +- oeps/best-practices/oep-0018-bp-python-dependencies.rst | 2 +- oeps/best-practices/oep-0019-bp-developer-documentation.rst | 2 +- oeps/best-practices/oep-0022-bp-django-caches.rst | 2 +- oeps/best-practices/oep-0037-bp-test-data.rst | 2 +- oeps/best-practices/oep-0038-Data-Modeling.rst | 2 +- oeps/processes/oep-0021-proc-deprecation.rst | 2 +- oeps/processes/oep-0054-core-contributors.rst | 3 ++- 8 files changed, 9 insertions(+), 8 deletions(-) diff --git a/oeps/best-practices/oep-0017-bp-feature-toggles.rst b/oeps/best-practices/oep-0017-bp-feature-toggles.rst index 9469b8252..db9ce6d57 100644 --- a/oeps/best-practices/oep-0017-bp-feature-toggles.rst +++ b/oeps/best-practices/oep-0017-bp-feature-toggles.rst @@ -1,5 +1,5 @@ OEP-17: Feature Toggles -######################### +####################### .. list-table:: :widths: 25 75 diff --git a/oeps/best-practices/oep-0018-bp-python-dependencies.rst b/oeps/best-practices/oep-0018-bp-python-dependencies.rst index f66a483ad..36498ca31 100644 --- a/oeps/best-practices/oep-0018-bp-python-dependencies.rst +++ b/oeps/best-practices/oep-0018-bp-python-dependencies.rst @@ -1,5 +1,5 @@ OEP-18: Python Dependency Management -###################################### +#################################### +-----------------+--------------------------------------------------------+ | OEP | :doc:`OEP-18 ` | diff --git a/oeps/best-practices/oep-0019-bp-developer-documentation.rst b/oeps/best-practices/oep-0019-bp-developer-documentation.rst index 183906151..a2fb7d11b 100644 --- a/oeps/best-practices/oep-0019-bp-developer-documentation.rst +++ b/oeps/best-practices/oep-0019-bp-developer-documentation.rst @@ -1,5 +1,5 @@ OEP-19: Developer Documentation -################################# +############################### .. list-table:: :widths: 25 75 diff --git a/oeps/best-practices/oep-0022-bp-django-caches.rst b/oeps/best-practices/oep-0022-bp-django-caches.rst index a6677aec6..e20ab98f5 100644 --- a/oeps/best-practices/oep-0022-bp-django-caches.rst +++ b/oeps/best-practices/oep-0022-bp-django-caches.rst @@ -1,5 +1,5 @@ OEP-22: Caching in Django -########################### +######################### +-----------------+--------------------------------------------------------+ | OEP | :doc:`OEP-22 ` | diff --git a/oeps/best-practices/oep-0037-bp-test-data.rst b/oeps/best-practices/oep-0037-bp-test-data.rst index 314d06212..96f048ef1 100644 --- a/oeps/best-practices/oep-0037-bp-test-data.rst +++ b/oeps/best-practices/oep-0037-bp-test-data.rst @@ -1,5 +1,5 @@ OEP-37: Dev Data -################## +################ .. list-table:: :widths: 25 75 diff --git a/oeps/best-practices/oep-0038-Data-Modeling.rst b/oeps/best-practices/oep-0038-Data-Modeling.rst index a7540fbe7..ab780153f 100644 --- a/oeps/best-practices/oep-0038-Data-Modeling.rst +++ b/oeps/best-practices/oep-0038-Data-Modeling.rst @@ -1,5 +1,5 @@ OEP-38: Data Modeling Best Practices -###################################### +##################################### +---------------+------------------------------------------------------------+ | OEP | :doc:`OEP-0038 ` | diff --git a/oeps/processes/oep-0021-proc-deprecation.rst b/oeps/processes/oep-0021-proc-deprecation.rst index 6cac0e80d..f464af34f 100644 --- a/oeps/processes/oep-0021-proc-deprecation.rst +++ b/oeps/processes/oep-0021-proc-deprecation.rst @@ -1,5 +1,5 @@ OEP-21: Deprecation and Removal -################################# +############################### +-----------------+--------------------------------------------------------+ | OEP | :doc:`OEP-21 ` | diff --git a/oeps/processes/oep-0054-core-contributors.rst b/oeps/processes/oep-0054-core-contributors.rst index 105897794..ccee5efe2 100644 --- a/oeps/processes/oep-0054-core-contributors.rst +++ b/oeps/processes/oep-0054-core-contributors.rst @@ -1,5 +1,6 @@ OEP-54: Core Contributors -########################### +######################### + .. list-table:: :widths: 25 75 From 3057abeae24f7e3c9bd4a3191f78da226cb6c63e Mon Sep 17 00:00:00 2001 From: Emad Rad Date: Sat, 9 Nov 2024 11:49:58 +0330 Subject: [PATCH 4/5] chore: typo fixed --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 4fda01336..fc7988767 100644 --- a/README.rst +++ b/README.rst @@ -18,7 +18,7 @@ View the published list of `Open edX Proposals (OEPs)`_ on ReadTheDocs. Getting Started *************** -This repository holds a bunch of text files, each of which represent an OEP or +This repository holds a bunch of text files, each of which represents an OEP or supplementary documentation. For browsing these OEPs, we recommend you read them in `their published form `_ on ReadTheDocs. From ea18ea4e7c6b504fd4ae7a662c01294a47c37145 Mon Sep 17 00:00:00 2001 From: Emad Rad Date: Sat, 9 Nov 2024 13:05:54 +0330 Subject: [PATCH 5/5] fix: grammatical errors --- .../oep-0055-proc-project-maintainers.rst | 42 +++++++++---------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/oeps/processes/oep-0055-proc-project-maintainers.rst b/oeps/processes/oep-0055-proc-project-maintainers.rst index 60b815779..952d3d74a 100644 --- a/oeps/processes/oep-0055-proc-project-maintainers.rst +++ b/oeps/processes/oep-0055-proc-project-maintainers.rst @@ -46,7 +46,7 @@ chosen, and how they work together. Overview ******** -The Open edX platform is a service oriented platform for authoring and +The Open edX platform is a service-oriented platform for authoring and delivering online learning based on the `Django framework`_. At the highest level, the platform is composed of numerous services (IDAs [#ida]_), micro-frontends (MFEs [#mfe]_) and libraries. The code for these @@ -57,7 +57,7 @@ Each component part of the Open edX platform requires maintenance to ensure that it meets, and continues to meet, the project definition of high quality. That definition will include project standards, appropriate documentation, and fitness for use, among other things. -That definition will evolve as project needs do and we learn what +That definition will evolve as the project needs to do and we learn what works and what doesn't. Component maintenance is work. To ensure that that work is done, a @@ -66,7 +66,7 @@ and held accountable for its performance. The Open edX project, like many projects, calls this role "maintainer." The notion of a project maintainer is typical of -open-source projects and widely considered a best practice [#maintainer]_. +open-source projects and is widely considered a best practice [#maintainer]_. The maintainer role is a leadership role that encompasses both technical and community management elements. Both dimensions of the role are equally @@ -87,7 +87,7 @@ Motivation ********** With the change in stewardship from edX to Axim Collaborative, -it is essential to have a well defined plan for maintaining +it is essential to have a well-defined plan for maintaining the platform. In order to ensure that the project is sustainable for the long term, @@ -95,7 +95,7 @@ maintenance must be shared by the entire community. The project must be robust enough that it can tolerate firms and contributors leaving the ecosystem. -As a project we must acknowledge that maintenance is hard work, but +As a project, we must acknowledge that maintenance is hard work, but work that must be done for the platform to be fit for use. The best way of ensuring this is to have a named person or persons who are responsible for getting the work done, a measurable definition of @@ -144,7 +144,7 @@ Historical Context Historically, the Open edX project has not had a well-defined role of maintainer. At times, community members stepped into this role informally. The role was also part of a broader "owner" role at edX. -Owners were also responsible for the health of the component they +Owners were also responsible for the health of the component(s) they owned both in the repository and in production; owners answered the pager when something went wrong. @@ -155,9 +155,9 @@ The role of the repository or project maintainer is both a community focused and a technical role [#role]_. Maintainers will be the public face of each component and should be welcoming and available. While maintainers should strive to always be friendly and kind in their -communication, firmness and directness are equally important. +communication, firmness, and directness are equally important. Maintainers must enforce the project's standards. In cases where a -proposed change isn't aligned with the our standards or direction, it +proposed change isn't aligned with our standards or direction, it is best to make that clear as early as possible. Non-technical responsibilities of maintainers include: @@ -204,7 +204,7 @@ See `Jobs of the Maintainer`_ for more details on these requirements. It is acceptable for a component to be maintained by a team or group as long as that arrangement does not reduce the reachability of at least one maintainer or -reduce accountability for the above responsibilities. The maintaining team must +reduce accountability for the above responsibilities. The maintenance team must have ways of direct contact, such as an email address and a GitHub team, that anyone can use to get hold of someone - it is completely acceptable for the team to figure out arrangements for list monitoring, such as an "on-call" @@ -221,13 +221,13 @@ In order to be a repository maintainer, you must * Abide by the Open edX `Code of Conduct`_ * Be a member of the `Core Contributor Program`_ with rights to the repository in question who has demonstrated excellence in the role of Core Contributor. - From time-to-time, in the case of a strong candidate and project need, core + From time to time, in the case of a strong candidate and project need, core contributor status and maintainer status may be conferred at the same time * In the case of repos being moved into the `openedx GitHub organization`_, be an original maintainer of the code We value the level of commitment that comes with being a Core Contributor and -think it is a necessary pre-requisite to becoming a Maintainer. We want to +think it is a necessary prerequisite to becoming a Maintainer. We want to ensure that the programs are congruent and not working at cross purposes; hours spent maintaining a component will count as Core Contributor hours. If we find that the requirement of being a Core Contributor limits participation in the @@ -237,7 +237,7 @@ Bootstrapping ============= Upon acceptance of this OEP, a bootstrapping period, starting with a small pilot -phase, will occur whereby 2U staff and community members will formally take on +phase will occur whereby 2U staff and community members will formally take on maintainership roles. Details of this period will be documented in the `maintainership documents`_ on the Open edX wiki, due to their rapidly changing nature. @@ -254,9 +254,9 @@ complete the critical activities. Coordination will typically be over asynchronous channels. -From time-to-time, a task force may be required to complete certain +From time to time, a task force may be required to complete certain project-wide responsibilities like developing repository standards, -as well as tools for measuring compliance to those standards. +as well as tools for measuring compliance with those standards. Becoming a Maintainer ===================== @@ -279,16 +279,16 @@ A new maintainer can be added in any of the following ways: teams-as-maintainers above). In both of the above cases, the request for maintainership change should be -publicized in Discourse with a comment period not less than two weeks. All +publicized in Discourse with a comment period of not less than two weeks. All community members are welcome to voice their support ("liking" the post does not -count), or comment with question/concerns. Existing maintainers and core +count) or comment with questions/concerns. Existing maintainers and core contributors may object to the nomination. If there is no objection from existing maintainers or core contributors at the end of the comment period, the role will be conferred. We are not currently limiting staff of companies from appointing, nominating, or voting for other employees of their company. This -would be impractical as, currently, single companies are locus of +would be impractical as, currently, single companies are the locus of component maintenance work. This may be addressed in future revisions to this proposal. @@ -309,12 +309,12 @@ conferred. If consensus cannot be reached lazily [#lazy_consensus]_, a vote of existing maintainers will be taken. Maintainers can approve a nomination with the approval -of at least three quarters of the members. +of at least three-quarters of the members. Removing a Maintainer ===================== -From time-to-time it will be necessary to remove a component +From time to time it will be necessary to remove a component maintainer. This might happen because: * A maintainer leaves the project or changes employment @@ -395,7 +395,7 @@ categories following questions: * What is the component for? - * How it fits into the overall platform? + * How does it fit into the overall platform? * What are its limitations and key areas of debt? * What new patterns or technologies should be adopted to improve the component? @@ -479,7 +479,7 @@ Notes can be seen in much literature that starts from the assumption that maintainers are essential and instead asks, what makes a maintainer great, what are the best-practices maintainers - should follow, how do we ensure maintainer don't burn out, how + should follow, how do we ensure maintainers don't burn out, how do we ensure critical parts of the software supply chain, like OpenSSL are maintained, etc. I have included some relevant materials in the **Source Material** section.