Skip to content

docs: add ADR for hidden permission categories and permissions - #633

Merged
BryanttV merged 2 commits into
mainfrom
bav/docs-hidden-permissions-adr
Nov 18, 2026
Merged

BryanttV merged 2 commits into
mainfrom
bav/docs-hidden-permissions-adr

Conversation

@BryanttV

@BryanttV BryanttV commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Description

ADR 0023 lets a role be hidden with the hidden flag, but permission categories and permissions have no equivalent. Compatibility permissions, such as the legacy_* permissions in the course_legacy category, must keep working but should not be offered when an administrator builds a custom role, nor listed in the permissions of the roles that grant them.

This PR adds ADR 0038, which proposes an optional hidden boolean (default false) on permission categories and permissions:

  • A permission is hidden when it sets hidden: true or when its category does.
  • Hidden permissions are left out of the role catalog permissions list and of each role's permissions list. The categories list only contains non-hidden categories that still have a visible permission.
  • Hiding is presentation only: definitions, role grants, permission checks, and the rendered Casbin policy do not change. A role whose permissions are all hidden is still listed, with an empty permissions list.
  • Role extensions cannot change hidden; it is set only where the category or permission is defined.
  • The flag is stored with the schema models, so it needs a migration.

Related docs updated:

  • docs/decisions/0023-extend-static-roles.rst: addendum extending "Hiding a role" to categories and permissions.
  • docs/decisions/0028-api-contract-for-role-catalog.rst: addendum amending the permissions, roles, and categories response rules.
  • docs/references/authorization-schema.rst: documents the hidden field for categories and permissions.

Affected roles: Developers and operators who define schemas; administrators using the Custom Roles feature (no behavior change until the implementation lands).

Supporting Information

  • ADR: docs/decisions/0038-hidden-permission-categories-and-permissions.rst
  • Related ADRs: 0023, 0025, 0028, 0031

Testing Instructions

  1. Check out this branch and build the docs.
  2. Open ADR and verify it renders correctly (headings, code blocks, references).
  3. Verify the new addenda in ADR 0023 and ADR 0028 render and that their links to ADR 0038 resolve.
  4. Check that the ADR content is consistent with ADRs 0023, 0025, 0028, and 0031.

Deadline

Willow

Other Information

This PR is documentation only; the schema models, migration, and catalog changes are in #634

@openedx-webhooks openedx-webhooks added open-source-contribution PR author is not from Axim or 2U core contributor PR author is a Core Contributor (who may or may not have write access to this repo). labels Nov 17, 2026
@openedx-webhooks

openedx-webhooks commented Nov 17, 2026 •

Copy link
Copy Markdown

Thanks for the pull request, @BryanttV!

This repository is currently maintained by @openedx/committers-openedx-authz.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

  • If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
    • This process (including the steps you'll need to take) is documented here.
  • If it doesn't, simply proceed with the next step.
🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

  • Dependencies

    This PR must be merged before / after / at the same time as ...

  • Blockers

    This PR is waiting for OEP-1234 to be accepted.

  • Timeline information

    This PR must be merged by XX date because ...

  • Partner information

    This is for a course on edx.org.

  • Supporting documentation
  • Relevant Open edX discussion forum threads
🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

Details
Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

  • The size and impact of the changes that it introduces
  • The need for product review
  • Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

@github-project-automation github-project-automation Bot moved this to Needs Triage in Contributions Nov 17, 2026
@BryanttV
BryanttV added this pull request to stack #635 November 17, 2026 17:26
@BryanttV
BryanttV force-pushed the bav/docs-hidden-permissions-adr branch from a9dd178 to 0a5e9c0 Compare November 17, 2026 17:34
@BryanttV BryanttV linked an issue Nov 17, 2026 that may be closed by this pull request
8 tasks
@BryanttV
BryanttV force-pushed the bav/docs-hidden-permissions-adr branch from 0a5e9c0 to 8f7e5bf Compare November 17, 2026 22:19
@BryanttV
BryanttV marked this pull request as ready for review November 17, 2026 22:19

@mariajgrimaldi mariajgrimaldi left a comment •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we also update https://github.com/openedx/openedx-authz/blob/main/src/openedx_authz/engine/schema/authz-schema-v1.json adding the new field? Thanks!

EDIT: I see we did it in #634

@mariajgrimaldi mariajgrimaldi left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This makes sense to me! Since the hidden field is only meant to control visibility and doesn't affect authorization behavior, I think it makes sense for hiding a category to also hide all its permissions.

Looks good to me!

@BryanttV
BryanttV force-pushed the bav/docs-hidden-permissions-adr branch from 33036d4 to 3d7d667 Compare November 18, 2026 15:28
BryanttV and others added 2 commits November 18, 2026 10:40
Document the optional `hidden` flag for permission categories and
permissions, and update the schema references and the role catalog and
role extension ADRs.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
@BryanttV
BryanttV force-pushed the bav/docs-hidden-permissions-adr branch from 3d7d667 to ad066f8 Compare November 18, 2026 15:40

@rodmgwgu rodmgwgu left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this!, it's consistent with what we discussed, so all good here!

@BryanttV
BryanttV merged commit b91ec8b into main Nov 18, 2026
8 checks passed
@BryanttV
BryanttV deleted the bav/docs-hidden-permissions-adr branch November 18, 2026 19:21
@github-project-automation github-project-automation Bot moved this from Needs Triage to Done in Contributions Nov 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

core contributor PR author is a Core Contributor (who may or may not have write access to this repo). open-source-contribution PR author is not from Axim or 2U

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

Add hidden property to permission categories and permissions

4 participants