Skip to content

Update the docs after the G1–G11 consolidation groups land #677

Open

Description

@zzylol

Context

The open PRs above #577 are being consolidated into groups G1–G11:

The user decided that these consolidation PRs do not change the Markdown docs. The docs are updated once, after the groups are done.

Docs to update after G1–G11

Many Markdown docs still describe the legacy search (MajorPass, global_selection, search_workload, the replacement strategies, dag_export, show_post_asap_ir, the legacy cost models). After the groups land they should describe the planning stages as implemented. Candidates, from the edits drafted in #676 and then reverted, and from the open docs PR #637:

  • User guides: docs/user_guide_docs/run-a-query.md (global_selection, the old binaries), stage-viewer.md (once G11 rebuilds the viewer on stage_pipeline).
  • Developer docs: library-api.md, asap-aware-mapping-architecture.md, asap-aware-mapping-contracts.md, extend-asap-aware-mapping.md, end-to-end-accuracy-guarantees.md, replacement-explanations.md, offline-sketch-evidence.md, physical-handoff-costs.md, storage-operation-costs.md, planner-vocabulary-migration.md, target-candidate-api-migration.md, metrics-observability-corpora.md, README.md.
  • Design docs (architecture, concepts and proposals that reference the legacy search): asap-aware-mapping.md, asap-aware-plan-search.md, evidence-dependent-candidates.md, input-output-workflow.md, updated_interface_with_pluggable_optimization.md, accuracy-models.md, planner-pipeline.md, post-asap-ir.md, the asap-aware-mapping/ proposals, asapquery-rule-coverage.md, error-resource-profile.md; the decisions concat-unique-keys.md and cse-cost-model.md (links to deleted files).
  • Root README.md and docs/README.md.

Conventions to follow

  • Names: use the planner-layering.md stage names. Code identifiers carry the stage number and name (stage0_query_language_frontends, stage1_logical_asap_optimization, stage2_physical_asap_optimization, stage3_plan_selection; the pipeline run_stage1_to_stage3 / Stage1ToStage3Pass).
  • Docs to leave alone: planner-layering.md and asap-primitive-schema.md keep their own wording, e.g. "language-specific frontends". Change them only if the user asks.
  • Superseded docs: mark docs that describe removed designs as historical rather than deleting them, unless the user decides otherwise.
  • Accuracy: describe actual behavior. Regenerate examples with stage_pipeline rather than writing expected numbers by hand.

Done when

No Markdown doc describes removed APIs as current, and the user guides' commands and examples run as written.

Related: #637 (open docs PR, to fold in or close), #676, #528.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions