release(3.0.0-beta.1): product version migration, beta gates, archive tooling and developer docs
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

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.
This commit is contained in:
cflmy committed 2026-11-22 02:31:32 +08:00
1 parent 56189b176c
commit 2c7c4f31e7
55 files changed
+3136 -453

No files matched your search

+128
View File
@@ -0,0 +1,128 @@
# Publishing and consuming a pure `.mq.md` library
A pure library is the preferred extension mechanism: it needs no core change,
no C ABI and no rebuild of `marqdo`. It is ordinary Markdown plus executable
sections.
## 1. Repository layout
```text
marqdo-quantum/
README.md
marqdo.yaml
index.mq.md
tests/
examples/
```
`marqdo.yaml`:
```yaml
project:
name: quantum
version: 0.1.0
marqdo: ">=3.0.0-beta.1,<4.0.0" # enforced against the running core
dependencies: {}
```
`index.mq.md`:
```markdown
# @knowledge 量子数学工具
此包在不修改 Marqdo 内核的情况下向外公开领域函数。
## @exec 加倍
`params(x: Int)`
`return x * 2`
```
Every exported function is an Exec H2. Its `params(...)` declaration is the
public contract; keep prose documentation in `@knowledge` sections or
paragraphs, which never execute.
## 2. How a consumer imports it
Pin a **full 40/64-character commit**; branches and tags are not reproducible:
```yaml
# consumer/marqdo.yaml
project:
name: quantum-consumer
version: 0.1.0
marqdo: ">=3.0.0-beta.1,<4.0.0"
dependencies:
quantum:
git: https://github.com/your-org/marqdo-quantum.git
rev: 0123456789abcdef0123456789abcdef01234567
```
```markdown
---
import:
quantum: "@quantum"
---
## @exec main
`return quantum.加倍(x=21)`
```
An `@alias` import binds the dependency's **entry package** (its
`index.mq.md`); qualify calls with the alias as above. A project-relative
dependency uses `path: ./deps/x` instead of `git`/`rev`. `marqdo add <alias>
--git <url> --rev <sha>` writes the dependency for you.
## 3. Lock and run
From the consumer project root:
```bash
marqdo lock # writes marqdo.lock (lock_version: 4)
marqdo sync --locked # verify cached content and materialize .marqdo/env; no fetch
marqdo check index.mq.md --refs
marqdo call index.mq.md main # prints 42
```
Rules that matter for reproducibility:
- With declared dependencies, `check`/`run`/`call` require `marqdo.lock` and
never fetch or rewrite it.
- Plain `marqdo sync` may fetch a pinned Git revision named by the lock;
`--locked` forbids fetching and fails if the verified cache is unavailable.
Both modes verify content digests and never silently update the lock.
- A dependency's content digest, manifest digest, instance id
(`dep:quantum@0.1.0#<digest>`) and alias edges are all recorded. Drift fails
with a "run `marqdo lock`" diagnostic.
- `project.marqdo` is enforced; a stale `>=0.1,<1` range is a hard
`package.marqdo_incompatible` error, not a warning.
## 4. Testing your library
Test it with the released binary only:
```bash
MARQDO_BIN=/opt/marqdo/marqdo
$MARQDO_BIN check index.mq.md
$MARQDO_BIN call index.mq.md 加倍 --arg x=21
```
Add a consumer fixture that pins a full SHA and assert the `--json` values and
diagnostics. For negative cases expect hard errors, never prose fallback:
- wrong arity/type → `call.arity` / a type diagnostic;
- unknown function → `symbol.unknown`;
- missing lock with dependencies → a `run marqdo lock` diagnostic;
- edited dependency content with a stale lock → lock/content-drift error.
## 5. Publishing checklist
- README with a minimal runnable example and the exact CLI product range.
- `marqdo.yaml` with an enforced `project.marqdo` range; functions with
`params(...)`; all examples migrated to RFC-LANG-0002.
- Tests pinned to a full commit SHA; no floating branches.
- State that the package is pure `.mq.md` and needs no plugin/provider/kernel.
- Version the package independently of the CLI (`0.1.0` here is the package
version, not the product version).