554fe520ea
- Introduced Rule 42: No Ontology Prefixes in Slot Names to enforce clean naming conventions. - Established Rule: No Rough Edits in Schema Files to ensure structural integrity during modifications. - Implemented Rule: No Version Indicators in Names to maintain stable semantic naming. - Created Rule: Ontology Detection vs Heuristics to emphasize the importance of verifying ontology definitions. - Defined Rule 50: Ontology-to-LinkML Mapping Convention to standardize mapping practices. - Added Rule: Polished Slot Storage Location to specify directory structure for polished slot files. - Enforced Rule: Preserve Bespoke Slots Until Refactoring to prevent unintended migrations during slot updates. - Instituted Rule 56: Semantic Consistency Over Simplicity to mandate execution of revisions in slot_fixes.yaml. - Added new Genealogy Archives Registry Enrichment class with multilingual support and structured aliases.
53 lines
1.4 KiB
Markdown
53 lines
1.4 KiB
Markdown
# 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:
|
|
```yaml
|
|
classes:
|
|
DigitalPlatformTransformationMetadata:
|
|
description: Metadata about record transformation steps.
|
|
```
|
|
|
|
❌ Wrong:
|
|
```yaml
|
|
classes:
|
|
DigitalPlatformV2TransformationMetadata:
|
|
description: Metadata about V2 transformation.
|
|
```
|