Files
marqdo-cli/docs/developers/compatibility.md
T
cflmy 2c7c4f31e7
Linux strict security lane (G-C) / strict isolation escape matrix (push) Waiting to run
ci/woodpecker/push/main Pipeline was successful
ci/woodpecker/manual/performance Pipeline was successful
CI / fmt + clippy + test (Linux x86_64) (push) Waiting to run
CI / schema instance validation + consumers (push) Waiting to run
CI / runtime contract (macos-latest) (push) Waiting to run
CI / runtime contract (windows-latest) (push) Waiting to run
release(3.0.0-beta.1): product version migration, beta gates, archive tooling and developer docs
REL-01: workspace/CLI/Analysis product version 3.0.0-beta.1 with updated
Cargo.lock; project.marqdo is enforced against the running core with
package.marqdo_range_invalid/package.marqdo_incompatible fail-closed
diagnostics; Tool SemVer prerelease negotiation tests; init template and
examples use the beta range. Verify init derives the project name from the
target directory instead of falling back to 'example'.

REL-02: beta support matrix is Linux x86_64 only; macOS/Windows are explicitly
experimental/unclaimed; strict policy and G4 Beta-only WARN are documented for
the release evidence.

REL-03: deterministic release packaging (tools/release/package.py) ships the
CLI and provider worker together with SOURCE_SHA, RELEASE_INFO.json,
known-limitations, specs, developer docs, examples incl. built plugin/provider
artifacts and consumers; tools/release/smoke.py cold-install tests the archive.

REL-04: docs/developers entry pages; corrected and self-contained third-party
integration handbook; stale Proposed/native-only/informational spec claims
fixed; release/status/compatibility/changelog/releasing docs updated.

REL-05: release_evidence.py gains an explicit beta profile
(BETA_RELEASE_CANDIDATE) distinct from the stable profile; Woodpecker build
step now packages and smoke-tests the archive on every pipeline.

Adds a runnable Resource Provider v2 example and corrects check --emit to
Analysis v2.
2026-11-22 02:31:32 +08:00

63 lines
3.4 KiB
Markdown

# Compatibility, versioning and support
This page summarizes the public support policy. The authoritative matrix is
[`../../COMPATIBILITY.md`](../../COMPATIBILITY.md); the beta policy is
[`../MARQDO_3_0_PRERELEASE_PLAN.md`](../MARQDO_3_0_PRERELEASE_PLAN.md).
## Version axes (do not conflate)
| Axis | `3.0.0-beta.1` value | Change rule |
|---|---|---|
| Product / CLI | `3.0.0-beta.1` | SemVer prerelease; breaking changes inside the 3.0 beta line are allowed and appear in `CHANGELOG.md`. |
| Analysis | v2 | New major for incompatible changes; consumers reject unknown majors. |
| Trace | v2 | New major for incompatible changes; binds to exact Analysis bytes. |
| CLI Tool | v1 | Frozen manifest/negotiation/bundle contract for v1. |
| Plugin ABI | v1 (`1.0`) | Frozen C layout and version negotiation. |
| Foreign wire | v1 | One-shot request envelope. |
| Provider manifest | v2 | `schema_version: 2`, `abi: c-abi-1`, `transport: worker`. |
| Lock | v4 | v3 requires an explicit `marqdo lock` migration; no silent reinterpretation. |
| Markdown profile | `marqdo.md.v1` | Frozen parser/options; the RFC-LANG-0002 mapping rewrite did not change the profile id. |
| Bundled stdlib | `0.1.0` | Independent package version; not the product version. |
| Plugin/tool/example packages | their own | Independent SemVer. |
`project.marqdo` and a tool's `compatibility.marqdo` are **enforced product
ranges**. Beta cores require a prerelease range such as
`>=3.0.0-beta.1,<4.0.0`; `>=3.0.0,<4.0.0` does not match a beta core.
## Platform support (`3.0.0-beta.1`)
| Platform | Release status | Notes |
|---|---|---|
| Linux x86_64 (glibc) | **Supported** | Only release archive: CLI + provider worker, same target triple. |
| Linux aarch64 | Not built | No artifact; source may build. |
| macOS arm64/x86_64 | Experimental, not claimed | Core may run; no macOS provider worker, no plugin ABI claim, no archive. |
| Windows x86_64 | Experimental, not claimed | Compile gate only; C ABI/plugin/provider/worker not claimed/fail-closed. |
Strict is Linux-only and probe-gated. Plugin/provider worker transports are not
OS sandboxes. `pure`/`project` are execution modes, not security boundaries.
## Language compatibility
`3.0.0-beta.1` implements RFC-LANG-0002 only. Pre-RFC `.mq.md` source
(Strong-execute / Emph-return / ordered-list branch / bullet-list loop /
block-quote call / first code-span signature) is **not executable**; there is no
`--legacy`, syntax switch or downgrade path. Migration is a rewrite task
documented in [`../migration/README.md`](../migration/README.md).
The earlier `cflmy/marqdo` product line is a different architecture; its source
syntax, package format and plugin ABI v2 are not compatible and no hidden
compatibility layer is provided.
## Beta policy
- Beta may break behavior with a changelog note; protocols are versioned
separately and only change with a new major.
- No LTS is announced. LTS is a later, evidence-based decision (see the
prerelease plan §3.2/§5), not a calendar promise.
- Known non-security gaps are listed in [release-limits.md](release-limits.md)
and in the release notes; unsupported requests must fail closed.
- G4 performance is a Beta-only `WARN` on the fixed Woodpecker agent for this
release; it is not a general performance guarantee.
- Every archive is checksummed and records its source SHA and toolchain.
Checksums prove integrity only, not publisher identity.