docs: add ADR for institution-defined tag code field

[mgwozdz-unicon]

Claude assisted...

Summary

• Proposes Tag.code, a generic, optional field on openedx_tagging's Tag model, to hold an institution's own competency identifier — distinct from CASE/CTDL and from the existing external_id field.
• Defines a completeness rule requiring code for every tag in a Competency Taxonomy, enforced through a generic property on Taxonomy that only a Competency Taxonomy subclass turns on, so openedx_tagging never has to know what a Competency Taxonomy is.
• Specifies assignment behavior: user-entered when given; a placeholder is generated only when a new tag is created with no code (via import or the existing Taxonomy Editing UI, which has no field for it yet); re-import can correct a placeholder but never clears or regenerates an existing value just because a file's column is blank.
• Answers openedx/openedx-core#625 ("Determine what and how many ID fields should be added to the Taxonomy data model").

Why

Competency Management UX designs show a "Competency ID" that institutions click to build competency-criteria associations. Institutions need their own internal identifier for this, separate from any future CASE/CTDL identifiers. The existing external_id field can't be reused: it's de facto immutable and is the load-bearing lookup key for import/export matching, so giving it a second, editable meaning would break that contract.

Status

Proposed. This is a recommendation for engineering and Open edX community review, not an implementation — no code changes are included in this PR.

Dependencies and follow-ups (tracked separately, not in this PR)

• #613 (implements the CompetencyTaxonomy model) needs to override the tag_code_required property this ADR defines. This ADR's property should land before or alongside [BE] Implement CBE core data models (CompetencyTaxonomy, criteria, learner status) #613, not after it — [BE] Implement CBE core data models (CompetencyTaxonomy, criteria, learner status) #613 depends on this ADR, not the reverse.
• #634 ("Taxonomy subclasses: embrace or deprecate?") is an open architecture discussion that could affect the subclass-override mechanism this ADR relies on.
• A pre-existing bug in the import validation path (a taxonomy-type cast gets discarded) needs its own fix for this ADR's completeness rule to work correctly.
• Implementation tickets for the data model change, GET endpoint exposure, import/export support, Competency Management UI display, and docs/release notes aren't filed yet.

These are called out in a comment on #625 rather than in the ADR itself.

[openedx-webhooks]

Thanks for the pull request, @mgwozdz-unicon!

This repository is currently maintained by @axim-engineering.

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:

• Overview of Review Process for Community Contributions
• Pull Request Status Guide
• Making changes to your pull request

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.