17  Migrating from Other Tools

Quarto-Needs provides conservative migration adapters for bringing requirements from other docs-as-code and requirements-management ecosystems into Quarto Markdown declarations. Migration is deliberately review-first: generating a plan never rewrites authored files.

17.1 Supported Tools

Source Tool Input Format Plan command
Sphinx-Needs needs.json quarto-needs migrate sphinx-needs <path> --output <plan.json>
Doorstop Directory of YAML/JSON documents quarto-needs migrate doorstop <dir> --output <plan.json>
StrictDoc .sdoc files / folder quarto-needs migrate strictdoc <path> --output <plan.json>
OpenFastTrace XML trace exchange quarto-needs migrate openfasttrace <path> --output <plan.json>

--output is the migration-plan JSON, not a destination .qmd file.

17.2 Migration Workflow

  1. Generate and review the migration plan. This does not modify destination files:

    quarto-needs migrate sphinx-needs docs/needs.json \
  --output .quarto-needs/migrations/sphinx-needs-plan.json

  2. Build a reviewed apply plan by assigning each source ID an explicit project-relative destination. Add any required type/relation mappings for the source model:

    quarto-needs migrate sphinx-needs docs/needs.json \
  --type-map req=functional-requirement \
  --destination REQ_001=requirements.qmd \
  --apply-plan

    Without --write, this still does not change authored files; the apply plan is written to .quarto-needs/migrations/sphinx-needs-apply-plan.json by default.

  3. Write only a ready, reviewed plan by repeating the reviewed mappings with --write:

    quarto-needs migrate sphinx-needs docs/needs.json \
  --type-map req=functional-requirement \
  --destination REQ_001=requirements.qmd \
  --apply-plan --write

  4. Validate the converted project:

    quarto-needs scan
quarto-needs check

For more than one source object, repeat --destination SOURCE_ID=path.qmd. --id-map SOURCE_ID=CANONICAL_ID is available when preserving the source ID is not appropriate. Writes are create-only and reject unresolved mappings, collisions, or unsafe destination paths rather than inferring identity.

17.3 Mapping Principles

  • Stable Identity: Existing IDs (e.g. REQ_001 or SYS-042) are preserved by default; remapping is explicit.
  • Relation Translation: Source links are mapped into the Quarto-Needs canonical relation catalog through explicit relation mappings where needed.
  • Review Before Mutation: Planning and apply-planning are non-mutating; --write is a separate, explicit step.
  • Quarto-Native Output: Ready candidates are rendered as standard Pandoc Div declarations (::: {.need ...} ... :::).