kempersc/glam
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
glam/.opencode/rules/no-version-indicators-in-names-rule.md
kempersc 86b9dcebff Refactor Digital Platform Classes and Introduce New Classes 
- Renamed DigitalPlatformV2DataSource to DigitalPlatformDataSource with updated description and mappings.
- Updated DigitalPlatformV2KeyContact to DigitalPlatformKeyContact, enhancing description and mappings.
- Refined DigitalPlatformV2OrganizationProfile to DigitalPlatformOrganizationProfile, improving description and slot usage.
- Revised DigitalPlatformV2OrganizationStatus to DigitalPlatformOrganizationStatus, clarifying description and mappings.
- Changed DigitalPlatformV2PrimaryPlatform to DigitalPlatformPrimaryPlatform, enhancing description and slot definitions.
- Updated DigitalPlatformV2Provenance to DigitalPlatformProvenance, refining description and mappings.
- Revised DigitalPlatformV2ServiceDetails to DigitalPlatformServiceDetails, improving description and mappings.
- Changed DigitalPlatformV2TransformationMetadata to DigitalPlatformTransformationMetadata, enhancing description and mappings.
- Added new classes: DetectionThreshold, DeviceType, DeviceTypes, DiarizationStatus, DigitalArchive, DigitalArchiveRecordSetType, DigitalArchiveRecordSetTypes, and DigitalConfidence with appropriate descriptions and mappings.
- Established rules for class descriptions, multilingual support, and slot definitions to ensure consistency and clarity across the schema.
2026-02-15 15:54:26 +01:00

1.4 KiB
Raw Permalink Blame History

Rule: No Version Indicators in Names

🚨 Critical

Do not include version identifiers in class names, slot names, or enum names.

Version tags in semantic names create churn, break reuse, and force unnecessary migrations.

The Rule

  1. Use stable semantic names for LinkML elements.

    • ✅ DigitalPlatform
    • ❌ DigitalPlatformV2

  2. If a model evolves, keep the name and update metadata/provenance.

    • Track revision in changelog, annotations, or transformation metadata.
    • Do not encode v2, v3, _2026, beta, final in the element name.

  3. Apply this to all naming surfaces:

    • classes: keys
    • slots: keys
    • enums: keys
    • name: values in module files

Allowed Versioning Locations

  • File-level changelog/comments
  • Dedicated metadata classes/slots (e.g., transformation metadata)
  • External release tags (git tags, manifest versions)

Migration Guidance

When you encounter versioned names:

  1. Rename semantic elements to stable names.
  2. Update references/imports/usages accordingly.
  3. Preserve provenance of the migration in comments/annotations.

Examples

✅ Correct:

classes:
  DigitalPlatformTransformationMetadata:
    description: Metadata about record transformation steps.

❌ Wrong:

classes:
  DigitalPlatformV2TransformationMetadata:
    description: Metadata about V2 transformation.