From fa1521a71e39df66793b2031d087519d632b2190 Mon Sep 17 00:00:00 2001 From: dimgigov Date: Mon, 27 Jul 2026 22:02:04 +0300 Subject: [PATCH] docs: sync documentation for v1.0.0 freeze Mark LanguageRef as normative, add docs index, update README/Packages/ Stdlib/BuildAndTest status lines, archive PLAN.md and QUALITY_PLAN pointers to RELEASE_v1.0.0 and active SEMVER. --- PLAN.md | 9 ++++++--- README.md | 17 +++++++++-------- docs/BuildAndTest.md | 3 +++ docs/LanguageRef.md | 7 ++++++- docs/Packages.md | 5 +++-- docs/QUALITY_PLAN.md | 4 ++-- docs/README.md | 17 +++++++++++++++++ docs/ROADMAP.md | 8 +++++--- docs/Stdlib.md | 11 ++++++++--- 9 files changed, 59 insertions(+), 22 deletions(-) create mode 100644 docs/README.md diff --git a/PLAN.md b/PLAN.md index 7ef0736..13d0d44 100644 --- a/PLAN.md +++ b/PLAN.md @@ -1,9 +1,12 @@ # Bux Programming Language — Roadmap to v1.0.0 -> **Version:** 0.3.1 (2026-06-06) -> **Bootstrap:** Nim (`bootstrap/`) — compiles `src/` → `buxc` +> **Historical document.** Language **v1.0.0** shipped 2026-07-27 (tag `v1.0.0`). +> For current status use: [`README.md`](README.md), [`docs/LanguageRef.md`](docs/LanguageRef.md), +> [`docs/RELEASE_v1.0.0.md`](docs/RELEASE_v1.0.0.md), [`docs/QUALITY_PLAN.md`](docs/QUALITY_PLAN.md). +> +> **Version (this file):** frozen archive of pre-1.0 planning +> **Bootstrap:** Nim (`bootstrap/`) — compiles `src/` → `buxc` > **Self-host:** Bux (`src/`) — compiles via `buxc` → `buxc2` -> **Target:** Bux v1.0.0 — fully self-hosting, gradual ownership, tooling --- diff --git a/README.md b/README.md index 9b85a6f..8bf4c9b 100644 --- a/README.md +++ b/README.md @@ -284,9 +284,9 @@ bux/ ├── tests/ # 🧪 Unit tests (Nim) ├── examples/ # Example programs ├── apps/ # Real-world applications -├── docs/ # Documentation +├── docs/ # Documentation (LanguageRef = v1.0 normative) ├── README.md -├── PLAN.md # Roadmap to v1.0.0 +├── PLAN.md # Historical roadmap (pre-1.0) └── Makefile ``` @@ -296,14 +296,15 @@ bux/ | Doc | Description | |-----|-------------| -| [`docs/LanguageRef.md`](docs/LanguageRef.md) | Language reference | +| [`docs/LanguageRef.md`](docs/LanguageRef.md) | **Normative** language reference (v1.0) | | [`docs/Stdlib.md`](docs/Stdlib.md) | Standard library API | -| [`docs/BuildAndTest.md`](docs/BuildAndTest.md) | Build, test, and tooling | -| [`docs/QUALITY_PLAN.md`](docs/QUALITY_PLAN.md) | Roadmap toward a “good” v1.0 | +| [`docs/BuildAndTest.md`](docs/BuildAndTest.md) | Build, test, cross, tooling | | [`docs/Packages.md`](docs/Packages.md) | Package manager + registry | -| [`docs/SEMVER.md`](docs/SEMVER.md) | Versioning policy | -| [`docs/ROADMAP.md`](docs/ROADMAP.md) | Feature status (constructs) | -| [`PLAN.md`](PLAN.md) | Long-form phase plan | +| [`docs/SEMVER.md`](docs/SEMVER.md) | Semver policy (**active** post-1.0) | +| [`docs/RELEASE_v1.0.0.md`](docs/RELEASE_v1.0.0.md) | v1.0.0 freeze notes | +| [`docs/ROADMAP.md`](docs/ROADMAP.md) | Language construct status | +| [`docs/QUALITY_PLAN.md`](docs/QUALITY_PLAN.md) | Session history + path to v1.0 (archive) | +| [`PLAN.md`](PLAN.md) | Historical phase plan (pre-1.0) | --- diff --git a/docs/BuildAndTest.md b/docs/BuildAndTest.md index cd5f7da..b8e4fab 100644 --- a/docs/BuildAndTest.md +++ b/docs/BuildAndTest.md @@ -1,5 +1,8 @@ # Build and Test Guide +> **Compiler:** **v1.0.0** — `./buxc --version` → `bux 1.0.0 (bootstrap)` +> Selfhost: `make selfhost` → `buxc2` reports `Bux 1.0.0 (self-hosting)`. + This guide covers building the Bux bootstrap compiler, creating projects, and running tests. --- diff --git a/docs/LanguageRef.md b/docs/LanguageRef.md index ad146d6..aedbdd3 100644 --- a/docs/LanguageRef.md +++ b/docs/LanguageRef.md @@ -1,6 +1,11 @@ # Bux Language Reference -This document describes the Bux programming language as implemented by the bootstrap compiler. +> **Status:** Normative for **v1.0.0** (language freeze). +> Describes Bux as implemented by the **bootstrap** (`buxc`, Nim) and **self-hosted** (`buxc2`) compilers. +> Behaviour here is the contract for semver after 1.0 — see [`SEMVER.md`](SEMVER.md) and [`RELEASE_v1.0.0.md`](RELEASE_v1.0.0.md). + +This document is the primary language specification. Compiler bugs that contradict +it are fixed without a MAJOR version bump; intentional breaking changes require MAJOR. --- diff --git a/docs/Packages.md b/docs/Packages.md index 5680773..4fa4b5d 100644 --- a/docs/Packages.md +++ b/docs/Packages.md @@ -1,8 +1,9 @@ # Bux Package Manager -> **Status:** Path + git + **local/file registry** (E.1) + **HTTP(S) index URL** (cached under `~/.bux/cache/`). +> **Status (v1.0):** Path + git + **local/file registry** + **HTTP(S) index URL** +> (cached under `~/.bux/cache/`). Lockfile + `bux install --locked` for CI. -See also: [SEMVER.md](SEMVER.md) for version policy. +See also: [SEMVER.md](SEMVER.md) for version policy (active as of language **v1.0.0**). --- diff --git a/docs/QUALITY_PLAN.md b/docs/QUALITY_PLAN.md index 316b832..1f1ed1a 100644 --- a/docs/QUALITY_PLAN.md +++ b/docs/QUALITY_PLAN.md @@ -94,7 +94,7 @@ |---|--------|------|--------| | E.1 | Package registry protocol (git/HTTP) | `bux add foo` без path hacks | ✅ local index + **HTTP(S) URL** cache + file/git + `search` | | E.2 | 3–5 production-quality apps в `apps/` | Showcase | ✅ 4 apps + `make test-apps` smoke (build + CLI) | -| E.3 | Language freeze + semver policy | Trust | ✅ draft `docs/SEMVER.md` | +| E.3 | Language freeze + semver policy | Trust | ✅ **v1.0.0** + active `docs/SEMVER.md` | | E.4 | Debugger/DWARF basics | Systems audience | ✅ `#line`→`.bux` + `-g` / `--release`; `make test-dwarf` | | E.5 | Benchmarks vs C/Zig/Nim (micro + nexus) | Marketing + regression | ✅ micro + C/Nim/Zig twins + `make bench-nexus` (wrk) | @@ -1212,7 +1212,7 @@ A (stdlib ergonomics) → B (compiler holes) → C (ownership depth) --- -## Платформен фокус (v0.5 → v1.0) +## Платформен фокус (v0.5 → v1.0 ✅) | Ниша | Какво значи за Bux | Статус / посока | |------|--------------------|-----------------| diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..e2aec32 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,17 @@ +# Bux documentation index + +**Language version:** **v1.0.0** (freeze) — tag `v1.0.0` + +| Document | Role | +|----------|------| +| [LanguageRef.md](LanguageRef.md) | **Normative** language specification | +| [Stdlib.md](Stdlib.md) | Standard library overview / API tables | +| [BuildAndTest.md](BuildAndTest.md) | Build, test, cross, static, containers | +| [Packages.md](Packages.md) | Manifests, registry, lockfiles | +| [SEMVER.md](SEMVER.md) | Versioning policy (active after 1.0) | +| [RELEASE_v1.0.0.md](RELEASE_v1.0.0.md) | v1.0.0 release / freeze notes | +| [ROADMAP.md](ROADMAP.md) | Language construct checklist | +| [QUALITY_PLAN.md](QUALITY_PLAN.md) | Session log + path to v1.0 (archive) | +| [api/stdlib.md](api/stdlib.md) | Generated API docs from `///` (via `make docs`) | + +Parent tree: [../README.md](../README.md) · historical plan: [../PLAN.md](../PLAN.md) diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index d85e1ff..63ac286 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,9 +1,11 @@ # Bux Language Roadmap — New Constructs -> **Updated:** 2026-07-27 | **Status:** ✅ Constructs for v1.0 shipped (language freeze) -> Recent: macros (`tt`/`type`/juxta), stdlib daily APIs, Linux/riscv smoke; see `docs/RELEASE_v1.0.0.md`. +> **Updated:** 2026-07-27 | **Status:** ✅ Constructs for **v1.0.0** shipped (language freeze) +> Recent: macros (`tt`/`type`/juxta), stdlib daily APIs, Linux/riscv smoke. +> Release: [`RELEASE_v1.0.0.md`](RELEASE_v1.0.0.md) · Spec: [`LanguageRef.md`](LanguageRef.md). -This document tracks planned language constructs beyond Phase 8 strategy. +This document tracks language constructs (historical + status). For the normative +spec use LanguageRef; for post-1.0 optional work see QUALITY_PLAN session 88 backlog. --- diff --git a/docs/Stdlib.md b/docs/Stdlib.md index 485c768..3ef6d8b 100644 --- a/docs/Stdlib.md +++ b/docs/Stdlib.md @@ -1,6 +1,11 @@ # Bux Standard Library -The Bux standard library provides core functionality for systems programming. All modules are merged into every compilation, so no explicit linking is needed. +> **Status:** Documented API for **v1.0.0**. Sources live under `lib/`; modules are +> merged into every compilation (no separate link step for stdlib). + +The standard library targets systems and cloud-on-Linux programming (I/O, collections, +net/TLS with full runtime, crypto, tasks/channels). Thin/static builds use +`BUX_RUNTIME=minimal` — see [BuildAndTest.md](BuildAndTest.md). --- @@ -280,8 +285,8 @@ func Main() -> int { let s: String = String_Replace("hello world", "world", "Bux"); PrintLine(s); // "hello Bux" - let fmt: String = String_Format2("{0} + {1} = magic", "Bux", "QBE"); - PrintLine(fmt); // "Bux + QBE = magic" + let fmt: String = String_Format2("{0} + {1} = magic", "Bux", "C"); + PrintLine(fmt); // "Bux + C = magic" let found: String = String_Find("hello world", "world"); if found as uint != 0 {