Schema Migrator Tool Index

Mô tả công cụ: schema_migrate.py

Script: /tools/migrate/schema_migrate.py

Mục đích: Khi /.okf/profile.yaml được nâng version (đặc biệt là major version bump), tool này bulk-update schema_version và bổ sung các required fields mới vào tất cả .md files trong repo.

Khi nào cần chạy

• Major version bump (1.0.0 → 2.0.0): bắt buộc, vì validator từ chối documents cũ sau khi upgrade.
• Minor version thêm required field mới: nên chạy để documents không bị warning.
• Patch version: không cần thiết.

Quy trình an toàn (phải tuân theo)

1. Tạo feature branch schema/migrate-v{version}.
2. Chạy --dry-run trước để preview thay đổi.
3. Nếu dry-run ổn, chạy --apply để ghi thực tế.
4. Mở MR và tag @rac-schema-owners để review trước khi merge.

Cách chạy

# Preview thay đổi (LUÔN chạy trước)
python tools/migrate/schema_migrate.py --dry-run --path .

# Áp dụng migration lên toàn repo
python tools/migrate/schema_migrate.py --apply --path .

# Target version cụ thể (mặc định = profile.yaml version)
python tools/migrate/schema_migrate.py --apply --target-version 2.0.0 --path .

# Chỉ migrate một directory
python tools/migrate/schema_migrate.py --apply --path services/

Hành vi khi gặp missing required fields

Tool tự động điền giá trị mặc định an toàn:

• schema_version → target version
• status → draft
• timestamp → current datetime UTC
• review_by → current + 90 ngày (operational types) hoặc + 365 ngày (structural types)
• tags, frameworks → empty list/dict

Lưu ý: Sau khi migrate, mọi file được điền giá trị default cần được engineer review và cập nhật giá trị thực tế.