Rule: Archive Folder Convention

Rule ID: archive-folder-convention
Created: 2026-01-14
Status: Active

Summary

All archived files MUST be placed in an /archive/ subfolder within their parent directory, NOT at the same level as active files.

Rationale

Clean separation: Active files are clearly distinguished from deprecated/archived files
Discoverability: Developers can easily find current files without wading through archived versions
Git history: Archive folder can be .gitignored for lightweight clones if needed
Consistent pattern: Same structure across all schema module types (slots, classes, enums)

Directory Structure

modules/
├── slots/
│   ├── archive/                    # Archived slot files go HERE
│   │   ├── branch_id_archived_20260114.yaml
│   │   ├── all_data_real_archived_20260114.yaml
│   │   └── ...
│   ├── has_or_had_identifier.yaml  # Active slots at this level
│   └── ...
├── classes/
│   ├── archive/                    # Archived class files go HERE
│   │   └── ...
│   └── ...
└── enums/
    ├── archive/                    # Archived enum files go HERE
    │   └── ...
    └── ...

Naming Convention for Archived Files

{original_filename}_archived_{YYYYMMDD}.yaml

Examples:

branch_id.yaml → archive/branch_id_archived_20260114.yaml
RealnessStatus.yaml → archive/RealnessStatus_archived_20260114.yaml

Migration Workflow

When archiving a file during slot migration:

# 1. Copy to archive folder with timestamp suffix
cp modules/slots/branch_id.yaml modules/slots/archive/branch_id_archived_20260114.yaml

# 2. Remove from active location
rm modules/slots/branch_id.yaml

# 3. Update manifest counts
# (Decrement slot count in manifest.json)

# 4. Update slot_fixes.yaml
# (Mark migration as processed: true)

Anti-Patterns

WRONG - Archived files at same level as active:

modules/slots/
├── branch_id_archived_20260114.yaml   # NO - clutters active directory
├── has_or_had_identifier.yaml
└── ...

CORRECT - Archived files in subdirectory:

modules/slots/
├── archive/
│   └── branch_id_archived_20260114.yaml   # YES - clean separation
├── has_or_had_identifier.yaml
└── ...

Validation

Before committing migrations, verify:

No *_archived_*.yaml files at module root level
All archived files are in archive/ subdirectory
Archive folder exists for each module type with archived files
Manifest counts updated to exclude archived files

2.8 KiB Raw Blame History