80 lines
4.5 KiB
Markdown
80 lines
4.5 KiB
Markdown
|
# Migrating from DocForge v1
|
||
|
|
|
||
|
|
DocForge2 preserves the `docforge` distribution, Python package, CLI command, MCP tool prefix,
|
||
|
|
generic project descriptor version, and legacy adapter entry point. Migration is an additive
|
||
|
|
validation exercise, not a canonical-content rewrite.
|
||
|
|
|
||
|
|
Read [compatibility](COMPATIBILITY.md), [legacy and no-AST operation](LEGACY_AND_NO_AST.md), and
|
||
|
|
[recovery](RECOVERY_AND_PERFORMANCE.md) before changing a production binding.
|
||
|
|
|
||
|
|
## What remains compatible
|
||
|
|
|
||
|
|
- Generic Markdown and TOML projects keep `.docforge/project.toml` schema version 1.
|
||
|
|
- A custom adapter implementing only `load_projection()` remains valid.
|
||
|
|
- Existing canonical nodes, stable IDs, source paths, relationship vocabulary, changesets, and
|
||
|
|
reviewed hashes are not silently rewritten.
|
||
|
|
- Existing CLI and MCP names remain available. New fields, commands, tools, plans, policies, and
|
||
|
|
reference integrations are additive.
|
||
|
|
- `docforge-mcp --no-ast` remains the shorthand for the preserved no-AST binding.
|
||
|
|
|
||
|
|
Disposable index and cache schemas may change. Rebuild them rather than copying them as authority.
|
||
|
|
|
||
|
|
## Recommended migration
|
||
|
|
|
||
|
|
1. Record the v1 package version, adapter identity, project descriptor, canonical source hash,
|
||
|
|
active changesets, generated client configuration, and current rendered outputs.
|
||
|
|
2. Back up canonical sources and active proposal files. Derived `.docforge/cache`, preview,
|
||
|
|
portable-graph, and viewer state need not be authoritative backups.
|
||
|
|
3. Install the DocForge2 candidate in a separate environment. Do not repoint the production MCP
|
||
|
|
binding yet.
|
||
|
|
4. Run the existing adapter through complete loading and `ProjectIndex.check()`. For incremental
|
||
|
|
adapters, verify complete/incremental equivalence. Logic-producing incremental adapters must
|
||
|
|
implement the independent complete assembly oracle.
|
||
|
|
5. Compare project ID, adapter, revision, source hash, primary node and edge hashes, Logic policy,
|
||
|
|
and retrieval results with the v1 evidence.
|
||
|
|
6. Recompose effective capability and projection policy. Do not assume that a new default grants
|
||
|
|
proposal, application, rendering, or viewer access.
|
||
|
|
7. Rebuild disposable indexes, extraction caches, fragments, receipts, previews, and portable
|
||
|
|
artifacts from the validated candidate.
|
||
|
|
8. Generate a new client fragment. Generic projects use `docforge configure`; custom adapters use
|
||
|
|
`AdapterLauncherV1` with `generate_adapter_client_configuration()`.
|
||
|
|
9. Run doctor, real MCP bootstrap, representative retrieval, rendering status, recovery, and
|
||
|
|
exact-hash proposal/application checks in a disposable or shadow environment.
|
||
|
|
10. Repoint one production binding only after the candidate and rollback procedure pass.
|
||
|
|
|
||
|
|
## Adopting reference adapters
|
||
|
|
|
||
|
|
The repository reference adapters are narrow syntax evidence, not automatic semantic replacements
|
||
|
|
for mature v1 integrations. Python publishes modules, classes, functions, and local imports.
|
||
|
|
JavaScript and TypeScript publish syntax plus static project-relative imports and re-exports.
|
||
|
|
C++ uses a confined `compile_commands.json` as inert translation-unit inventory and publishes
|
||
|
|
directly resolvable project-local quoted includes.
|
||
|
|
|
||
|
|
Do not replace a compiler-, language-server-, or project-owned semantic adapter if the task depends
|
||
|
|
on resolved calls, types, inheritance, macros, compiler include semantics, runtime facts, or
|
||
|
|
ownership. Use [reference adapters](REFERENCE_ADAPTERS.md) as a measured starting point.
|
||
|
|
|
||
|
|
## Changesets
|
||
|
|
|
||
|
|
Existing changesets remain bound to their original project, root, base revision, source hash,
|
||
|
|
writer, operations, and exact hash. Do not edit a changeset to make it look current. Retrieve and
|
||
|
|
validate it through the candidate. Rebase only when every precondition remains true; otherwise
|
||
|
|
create and review a new proposal.
|
||
|
|
|
||
|
|
Before enabling canonical application, prove the exact serializer round trip and recovery behavior
|
||
|
|
for the selected adapter. The fixed reference MCP server is intentionally read-only.
|
||
|
|
|
||
|
|
## Rollback
|
||
|
|
|
||
|
|
Keep the v1 environment, configuration fragment, and service definition until the DocForge2
|
||
|
|
binding has passed live validation. To roll back:
|
||
|
|
|
||
|
|
1. Stop the DocForge2 MCP/viewer processes.
|
||
|
|
2. Restore the previous client or service binding.
|
||
|
|
3. Restore canonical sources only if a verified application receipt says they changed and the
|
||
|
|
adapter-specific rollback requires it.
|
||
|
|
4. Discard DocForge2-derived indexes, receipts, fragments, previews, and portable artifacts.
|
||
|
|
5. Restart v1 and verify its recorded project/source identity.
|
||
|
|
|
||
|
|
Never move a published tag or reuse a version identity for a corrected release.
|