TaskNotes

8. Compatibility and Migrations

8.1 Purpose

This section defines how implementations transition from historical behavior to canonical specification behavior without silent data breakage.

8.2 Compatibility modes

Implementations MAY support compatibility modes for legacy behavior.

If supported, compatibility modes MUST:

  • be explicitly enabled or disabled,
  • be discoverable through configuration or capability metadata,
  • not be silently enabled by default in new collections.

8.3 Migration expectations

When canonical behavior differs from historical behavior, implementations SHOULD provide:

  1. deterministic migration rules,
  2. dry-run preview support,
  3. rollback-safe workflow guidance.

8.4 Alias normalization migration

For legacy key aliases, a migration SHOULD:

  • read both canonical and alias keys,
  • choose canonical value deterministically (recommended: canonical key precedence),
  • rewrite persisted file using canonical keys,
  • preserve unrelated unknown fields.

8.4.1 Example

Before:

recurrenceAnchor: scheduled
recurrence_anchor: completion

After normalization:

recurrenceAnchor: scheduled

With warning:

  • alias_conflict_ignored: alias value ignored because canonical key present.

8.5 Temporal normalization migration

If historical writes include mixed datetime styles, migration SHOULD normalize to canonical UTC ISO Z for datetime roles while preserving date-only roles as dates.

Example:

Before:

dateCreated: 2026-02-20 10:00:00+00:00

After:

dateCreated: 2026-02-20T10:00:00Z

8.6 Recurrence state migration

If historical data allows overlapping complete/skip dates, migration MUST resolve overlap deterministically.

Recommended resolution policy:

  • if overlap exists, prefer most recent user action where recoverable,
  • otherwise prefer complete_instances and remove overlapping skip entries,
  • emit migration report for affected dates.

Policy choice MUST be documented.

8.7 Dependency migration

When migrating legacy dependency data, implementations SHOULD:

  • normalize dependency key names to mapped canonical key,
  • ensure each entry has uid and canonical reltype,
  • normalize legacy string/path references into configured canonical reference style,
  • remove duplicate dependency entries by policy.

If historical data omits reltype, migration MAY apply dependencies.default_reltype and SHOULD report count of inferred values.

8.8 Reminder migration

When migrating legacy reminder data, implementations SHOULD:

  • normalize reminder key names,
  • normalize type values to canonical enum (absolute or relative),
  • normalize relatedTo values to canonical enum (due or scheduled),
  • normalize absoluteTime to canonical UTC ISO Z,
  • validate and normalize offsets to ISO 8601 duration syntax.

If reminder id values are missing, migration MAY generate IDs and MUST report generated count.

When migrating legacy link values, implementations SHOULD:

  • normalize supported link syntaxes according to §11 parsing rules,
  • preserve alias and anchor components where possible,
  • normalize resolved targets into canonical write format by policy,
  • detect and report ambiguous links instead of silently choosing non-deterministically.

8.10 Divergence register

Implementations SHOULD maintain a divergence register with columns:

  • section
  • current behavior
  • target canonical behavior
  • migration strategy
  • deprecation timeline

8.11 Deprecation policy

For any behavior deprecated by the specification:

  1. announce deprecation in release notes,
  2. provide warning period,
  3. provide migration tooling where feasible,
  4. remove deprecated behavior only in a version aligned with compatibility commitments.

8.12 Data safety requirements

Migrations MUST NOT:

  • silently drop unknown fields,
  • silently convert valid date-only fields to datetime,
  • silently rewrite recurrence semantics without explicit policy,
  • silently drop unresolved dependency entries,
  • silently rewrite link targets to different destinations without explicit policy,
  • silently delete reminders unless explicitly requested.

8.13 Suggested migration report format

spec_version_from: 0.1.0-draft
spec_version_to: 0.1.0
files_scanned: 214
files_changed: 67
warnings:
  alias_conflict_ignored: 3
  instance_state_overlap_resolved: 2
  unresolved_dependency_target: 4
changes:
  normalized_datetime_fields: 41
  alias_keys_removed: 29
  instance_overlaps_fixed: 2
  inferred_dependency_reltype: 5
  generated_reminder_ids: 8
  normalized_link_targets: 14

8.14 Compatibility statement example

Compatibility mode: legacy-aliases=true, legacy-timeentry-duration=true
Planned removal: v2.0.0
Migration command: tasknotes migrate --normalize-frontmatter