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
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:
1 parent
56189b176c
commit
2c7c4f31e7
55 files changed
+3136
-453
No files matched your search
@@ -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).
|
||||
Reference in new issue
Block a user