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

+84
View File
@@ -0,0 +1,84 @@
# Quickstart: install and run
Product: `3.0.0-beta.1` (Linux x86_64 beta). Install a **release archive**, not
a source checkout, when you only consume Marqdo.
## 1. Install the archive
```bash
sha256sum -c marqdo-3.0.0-beta.1-x86_64-unknown-linux-gnu.tar.gz.sha256
tar -xzf marqdo-3.0.0-beta.1-x86_64-unknown-linux-gnu.tar.gz
cd marqdo-3.0.0-beta.1-x86_64-unknown-linux-gnu
./marqdo --version # marqdo 3.0.0-beta.1
./marqdo --help
```
Keep `marqdo` and `marqdo-provider-worker` in the **same directory**. The
provider helper is resolved as a sibling; there is no `PATH` fallback, and a
missing helper fails closed with `ext.worker_unavailable`. You can move the whole
directory or add it to `PATH`:
```bash
export PATH="$PWD:$PATH"
marqdo --version
```
## 2. First project
```bash
marqdo init demo
cd demo
marqdo check index.mq.md
marqdo run index.mq.md
marqdo call index.mq.md main
```
`init` writes `marqdo.yaml` (with the enforced
`marqdo: ">=3.0.0-beta.1,<4.0.0"` range), an RFC-LANG-0002 `index.mq.md` and a
`.gitignore`; it does not create a lock, env or git repository.
```markdown
## @exec main
`问候 = "你好,Marqdo"`
`打印(问候)`
`return 问候`
```
`run` executes the entry function (`main` by default) and prints program output;
`call` prints the returned value. Use `--json` for machine-readable
results (`{"command":"run","success":true,...}`), including embedded program
stdout and diagnostics.
## 3. Language in one screen
- An H2 marked `@exec` is a callable function; `@knowledge` sections are inert
documentation. Unmarked headings inherit the nearest ancestor mode.
- `**strong**`, `*emph*` and inline `` `code` `` are interchangeable carriers of
one statement each.
- Control flow uses keywords: `if`/`else`/`while`/`end`, plus `params(...)` and
`return`.
- Lists, block quotes and paragraphs are presentation only.
- The normative contract is
[`../architecture/RFC-LANG-0002-unified-semantics.md`](../architecture/RFC-LANG-0002-unified-semantics.md),
[`../../spec/mapping.md`](../../spec/mapping.md) and
[`../../spec/expression.ebnf`](../../spec/expression.ebnf).
## 4. Machine-readable output
```bash
marqdo check index.mq.md --json
marqdo run index.mq.md --json
marqdo call index.mq.md main --json
```
## 5. Where next
- Publish/consume a pure library: [libraries.md](libraries.md).
- Build an external tool: [tools.md](tools.md).
- Plugins, kernels, providers: [extensions.md](extensions.md).
- Analysis/Trace consumers: [analysis-trace.md](analysis-trace.md).
- Version axes and platform support: [compatibility.md](compatibility.md).
- Beta limitations: [release-limits.md](release-limits.md).