docs: add ADR for competency taxonomy detection - #662
Conversation
openedx_tagging needs a layering-safe way to report whether a Taxonomy is competency-enabled (openedx#618), without gaining any knowledge of the CompetencyTaxonomy subclass CBE owns. Adds a taxonomy_type field to the base Taxonomy model set by the caller that creates a CompetencyTaxonomy row, and documents why two prior approaches on openedx#618 (an openedx_tagging-side hasattr check, an overridable get_type() method) were unsound. Amends ADR 0002 to note the corresponding creation-time invariant and that its rejection of a flat taxonomy_type column still stands, unaffected by this narrower field.
openedx-webhooks
added
the
open-source-contribution
|
Thanks for the pull request, @mgwozdz-unicon! This repository is currently maintained by 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 approvalIf you haven't already, check this list to see if your contribution needs to go through the product review process.
🔘 Provide contextTo 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:
🔘 Get a green buildIf one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green. DetailsWhere 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:
💡 As a result it may take up to several weeks or months to complete a review and merge your PR. |
ADR 0013 no longer decides to add a taxonomy_type field to Taxonomy: an architecture-meeting review moved that decision to detecting competency taxonomies entirely within openedx-platform instead. The lifecycle-rule note and Rejected Alternatives cross-reference this amendment added to describe that field's creation-time invariant no longer describe anything that happens, so revert ADR 0002 to its state from before the amendment.
The next commit changes this ADR's decision away from a taxonomy_type field, so the filename no longer describes it. Renamed on its own, ahead of that content change, so the rename and the content diff stay independently reviewable.
Reversed at the 2026-07-21 architecture meeting: instead of a taxonomy_type field on the base Taxonomy model, report a taxonomy's type entirely within openedx-platform (a hasattr check on the same already-fetched instance, plus a matching select_related), so openedx_tagging and the CBE app stay fully free of any competency-specific reference. The field-based approach is demoted to Rejected Alternatives, alongside two more precise variants (two-call create flow, combined REST API) that were previously folded into a single vaguer entry. Adds a diagram of the chosen approach.
Replace references to openedx-platform's specific serializer/view class and method names, and the literal hasattr()/select_related() calls, with a description of the mechanism itself. Those identifiers belong to a repo this ADR doesn't govern, so naming them risked the ADR reading as stale if openedx-platform's internal structure changes, even though the decision itself wouldn't have.
Drop the TaxonomySerializer parenthetical (an openedx_tagging class name that isn't needed to state the requirement), the redundant CompetencyTaxonomy(Taxonomy) Python-syntax notation (already said in prose just before it), and the parenthetical GitHub issue references, which read oddly in an ADR meant to stand on its own.
|
We discussed this at today's architecture meeting and decided to go with option 4: keep the type-detection check, and its I've updated ADR 0013 to reflect that: status is now Accepted, the Decision section describes the openedx-platform-side approach with a diagram, and the original field-based approach is now the first Rejected Alternative with the reasoning above. I also split the "frontend-only" alternative into the two more precise variants we actually compared in the table above (the two-call create flow and the combined REST API), and reverted the ADR 0002 amendment since it no longer describes anything that happens now that there's no new field. The changes are spread across five commits so the diff stays easy to review: a revert of the ADR 0002 amendment, a pure rename of the ADR file with zero content diff, the actual decision rewrite, and two small follow-up commits trimming implementation detail (specific class/method names, and parenthetical issue references) out of the Context and Decision sections. @bradenmacdonald, could you take another look when you get a chance? Let me know if I've mischaracterized anything about option 4 above. |
mgwozdz-unicon
changed the title
github-project-automation
Bot
moved this from Ready for Review
to Done
in Contributions
5 participants
Summary
openedx_tagging's taxonomy Get endpoints need to report whether a taxonomy is a Competency Taxonomy (#618), symmetrically with the Create/Import endpoint'staxonomy_typefield (#614).This PR adds ADR 0013 (
openedx_tagging), deciding to report a taxonomy's type entirely within openedx-platform: its serializer and view, which already override the base ones, check whether a relatedCompetencyTaxonomyrow exists for a givenTaxonomyand fix the resulting query cost, with no new field, method, or enum value added toopenedx_taggingor the CBE app.An earlier draft of this ADR instead proposed a
taxonomy_typefield directly onTaxonomy. Following architecture-team review, that approach and four others considered along the way are documented as Rejected Alternatives in the ADR itself.Context
taxonomy_typetaxonomy_typefield (this ADR's read-side value mirrors it)get_type()method)openedx_learning) —CompetencyTaxonomymulti-table-inheritance model; the DB relation this decision relies onopenedx_tagging) — prior art foropenedx_tagging-owned ADRsdriven by CBE needs