docs: clarify Claro v1 status and validation
This commit is contained in:
Hermes Agent
@@ -0,0 +1,229 @@
|
||||
# Claro v1.18.26 Documentation Audit
|
||||
|
||||
Date: 2026-06-05
|
||||
|
||||
## Scope
|
||||
|
||||
Reviewed the Markdown documentation in the Claro v1.18.26 package:
|
||||
|
||||
- `README.md`
|
||||
- `CHANGELOG.md`
|
||||
- `lessons/README.md`
|
||||
- `docs/*.md` — 55 files
|
||||
|
||||
Total Markdown files inventoried: 57.
|
||||
|
||||
## Overall finding
|
||||
|
||||
This audit is a historical snapshot from the first v1.18.26 documentation cleanup pass. At audit time, the docs were useful and broad, but they read like a historical bundle plus a current release bundle. That was okay for internal development, but before a polished public release the documentation needed to be reorganized so beginners saw one clear current path and advanced/history material was separated.
|
||||
|
||||
The cleanup notes at the end of this file record the follow-up work that has already been completed. For current learner guidance, use `CURRENT_STATUS.md`, `ROADMAP.md`, and the README documentation map before relying on the problem list below.
|
||||
|
||||
## Current strongest documentation
|
||||
|
||||
These docs are clear and should remain part of the current user-facing docs:
|
||||
|
||||
- `README.md` — good high-level overview of Claro v1.18.26.
|
||||
- `docs/QUICK_START.md` — important beginner entry point.
|
||||
- `docs/FIRST_HOUR.md` — useful learner sequence.
|
||||
- `lessons/README.md` — useful for guided learning.
|
||||
- `docs/CLI.md` — needed command reference.
|
||||
- `docs/SPEC.md` — core language reference.
|
||||
- `docs/ERRORS.md` — important for beginner-friendly diagnostics.
|
||||
- `docs/FORMATTER.md`
|
||||
- `docs/LINTER.md`
|
||||
- `docs/TESTING.md`
|
||||
- `docs/ADVANCED_STATIC_TYPING.md`
|
||||
- `docs/IDE.md`
|
||||
- `docs/CONCURRENCY.md`
|
||||
- `docs/V1_15_OBJECTS_CLASSES.md`
|
||||
- `docs/V1_16_PACKAGES_PROJECTS.md`
|
||||
- `docs/V1_17_NETWORKING.md`
|
||||
- `docs/SDL12.md`
|
||||
- `docs/FUTURE_FEATURES_ROADMAP.md`
|
||||
|
||||
## Main documentation problems found at audit time
|
||||
|
||||
### 1. Old RC language is still mixed with current docs
|
||||
|
||||
At audit time, several docs still said or implied that Claro was in an old release-candidate phase:
|
||||
|
||||
- `docs/ROADMAP.md` still says:
|
||||
- `RC3 - Classroom Readiness`
|
||||
- `RC4 - Final Polish`
|
||||
- `1.0 - Stable Beginner Release`
|
||||
- `docs/CLASSROOM_READINESS.md` says `Claro RC3 is suitable... but not final 1.0`.
|
||||
- `docs/LINTER.md` says `RC3 catches:`.
|
||||
- `docs/TESTING.md` mentions validating an RC3 package and `validate_rc3.py`.
|
||||
- `docs/FIRST_HOUR.md` references `RC2` behavior.
|
||||
|
||||
Recommendation: keep historical RC docs, but move them under a clear `docs/history/` section or label them as historical at the top.
|
||||
|
||||
### 2. Current version story is inconsistent
|
||||
|
||||
The package is v1.18.26, but several docs are tied to old versions:
|
||||
|
||||
- `docs/STABLE_RELEASE.md` is specifically `Claro v1.10.26 Stable Release`.
|
||||
- `docs/POST_1_0_ROADMAP.md` lists old future milestones like v1.11.26 through v1.15.26, even though many are already superseded.
|
||||
- `docs/V1_14_STATIC_TYPES.md`, `docs/V1_15_OBJECTS_CLASSES.md`, etc. are useful but read like version-specific release notes instead of current feature docs.
|
||||
|
||||
Recommendation: use current feature docs for beginners and keep old version docs as historical release notes.
|
||||
|
||||
### 3. The complete-platform roadmap needs to be promoted
|
||||
|
||||
`docs/FUTURE_FEATURES_ROADMAP.md` is the best roadmap for the complete beginner-language goal:
|
||||
|
||||
1. Advanced static typing
|
||||
2. IDE support
|
||||
3. Concurrency
|
||||
4. Web programming
|
||||
5. GUI/game engine
|
||||
6. Package registry
|
||||
7. Optimization
|
||||
|
||||
But it should now explicitly reflect the user's desired completion targets:
|
||||
|
||||
- SDL graphics
|
||||
- classes/objects
|
||||
- package manager
|
||||
- networking
|
||||
- threads/concurrency
|
||||
- strong static types
|
||||
- advanced IDE support
|
||||
|
||||
Recommendation: rename or supplement it with `docs/COMPLETE_PLATFORM_ROADMAP.md` and track each feature as Not Started / Foundation / Beta / Stable.
|
||||
|
||||
### 4. SDL graphics are correctly marked as not stable, but need a clearer beginner path
|
||||
|
||||
`docs/SDL12.md` is honest and says SDL is not included in the current stable executable. That is good.
|
||||
|
||||
Current status:
|
||||
|
||||
- Placeholder graphics commands exist.
|
||||
- Real SDL commands are planned/experimental.
|
||||
- `examples/experimental_sdl/` will fail with current `claro.exe`.
|
||||
|
||||
Recommendation: add `docs/GRAPHICS.md` with two tracks:
|
||||
|
||||
- Current: beginner-safe placeholder graphics commands.
|
||||
- Future: optional SDL backend behind a build flag.
|
||||
|
||||
### 5. Advanced IDE support has a foundation, not a complete IDE experience
|
||||
|
||||
`docs/IDE.md` documents:
|
||||
|
||||
- `claro ide`
|
||||
- metadata JSON
|
||||
- completion list
|
||||
- diagnostics helper
|
||||
|
||||
Missing for a complete beginner platform:
|
||||
|
||||
- syntax highlighting package
|
||||
- real LSP server or editor extension
|
||||
- hover help
|
||||
- go-to definition
|
||||
- code actions/fixes
|
||||
- integrated lesson/help flow
|
||||
|
||||
Recommendation: add `docs/EDITOR_EXTENSION_PLAN.md` or expand `docs/IDE.md` with a phased roadmap.
|
||||
|
||||
### 6. Static types are currently partial
|
||||
|
||||
`docs/ADVANCED_STATIC_TYPING.md` clearly documents typed lists and maps checked by `claro typecheck`.
|
||||
|
||||
Missing for strong static types:
|
||||
|
||||
- function parameter types
|
||||
- function return types
|
||||
- object method type checking
|
||||
- typed imports
|
||||
- better type checking across branches/loops
|
||||
- runtime enforcement strategy for containers
|
||||
|
||||
Recommendation: add a `Strong Static Types` section to the roadmap and keep the beginner syntax examples very small.
|
||||
|
||||
### 7. Concurrency is deterministic foundation, not real threads yet
|
||||
|
||||
`docs/CONCURRENCY.md` is clear that Claro has cooperative concurrency foundations and no native threads yet.
|
||||
|
||||
Missing for complete platform:
|
||||
|
||||
- real cooperative scheduler
|
||||
- cancellation
|
||||
- timeouts
|
||||
- message passing
|
||||
- eventually optional native threads only if safe
|
||||
|
||||
Recommendation: avoid saying "threads" in user-facing docs until semantics are safe; use "tasks" first.
|
||||
|
||||
### 8. Package manager foundation exists, but registry is not complete
|
||||
|
||||
`docs/V1_16_PACKAGES_PROJECTS.md` documents local package workflow, manifests, lock files, and safety rules.
|
||||
|
||||
Missing for full package ecosystem:
|
||||
|
||||
- dependency versions
|
||||
- local install from path
|
||||
- package publish/export
|
||||
- remote registry protocol
|
||||
- signature/checksum verification for downloaded packages
|
||||
|
||||
Recommendation: add `docs/PACKAGE_REGISTRY.md` before implementing online downloads.
|
||||
|
||||
### 9. Networking foundation exists, web server does not
|
||||
|
||||
`docs/V1_17_NETWORKING.md` is good for HTTP client commands and offline `claro://` URLs.
|
||||
|
||||
Missing for complete platform:
|
||||
|
||||
- beginner web server syntax
|
||||
- routes
|
||||
- request/response objects
|
||||
- local-only safe server mode
|
||||
- docs and examples for web apps
|
||||
|
||||
Recommendation: add `docs/WEB_SERVER_PLAN.md` before implementing sockets.
|
||||
|
||||
## Recommended cleanup order from the original audit
|
||||
|
||||
1. Add a `docs/CURRENT_STATUS.md` file with a plain feature matrix for v1.18.26.
|
||||
2. Rewrite `docs/ROADMAP.md` so it no longer describes RC3/RC4 as current.
|
||||
3. Move or label RC docs as historical.
|
||||
4. Split docs into beginner-facing vs maintainer/history docs.
|
||||
5. Add complete-platform roadmap docs for:
|
||||
- strong static types
|
||||
- IDE/editor support
|
||||
- cooperative tasks/threads
|
||||
- package registry
|
||||
- web server/networking
|
||||
- SDL graphics
|
||||
- object/class polish
|
||||
6. Update `README.md` to point beginners only to current docs.
|
||||
|
||||
## Feature status summary
|
||||
|
||||
- Beginner scripting core: stable foundation.
|
||||
- Classes/objects: foundation present; needs polish and stronger typing.
|
||||
- Package manager: local foundation present; registry incomplete.
|
||||
- Networking: HTTP client foundation present; web server incomplete.
|
||||
- Threads/concurrency: cooperative foundation present; real scheduling/threads incomplete.
|
||||
- Strong static types: typed variables and containers foundation present; function/object/import typing incomplete.
|
||||
- Advanced IDE support: metadata/helper foundation present; full editor/LSP experience incomplete.
|
||||
- SDL graphics: not included in stable executable; experimental/planned only.
|
||||
|
||||
## Bottom line
|
||||
|
||||
Documentation is good enough for internal development, but before the complete beginner-language release it needs a current-status pass. The largest documentation problem is not missing docs; it is that historical RC/version docs are mixed into the current package without clear labeling.
|
||||
|
||||
|
||||
## Cleanup pass completed
|
||||
|
||||
A documentation cleanup pass was applied after this audit:
|
||||
|
||||
- Added `CURRENT_STATUS.md`.
|
||||
- Rewrote `ROADMAP.md` so old RC3/RC4/1.0 milestones are no longer presented as current.
|
||||
- Added complete-platform planning docs: `COMPLETE_PLATFORM_ROADMAP.md`, `GRAPHICS.md`, `PACKAGE_REGISTRY.md`, `WEB_SERVER_PLAN.md`, and `EDITOR_EXTENSION_PLAN.md`.
|
||||
- Updated `README.md` with a beginner-first documentation map.
|
||||
- Updated stale current-facing docs: `CLASSROOM_READINESS.md`, `LINTER.md`, `TESTING.md`, `FIRST_HOUR.md`, `SPEC.md`, and `POST_1_0_ROADMAP.md`.
|
||||
- Labeled RC and older validation/release files as historical.
|
||||
Reference in New Issue
Block a user