Aksara [v0.7.1] — Documentation & Developer Experience #32
nagarjuna-tella
announced in
Announcements
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
Aksara v0.7.1 focuses on a different kind of framework correctness:
public truth.
After the Durable Authorized Operations work in v0.7.0, the framework had reached the point where its capabilities were growing faster than its public explanation.
v0.7.1 rebuilds the developer experience around one principle:
This release introduces no intentional runtime capability or semantic change. Instead, it audits, rewrites, executes, and verifies the public surface around the existing v0.7 backend.
A clearer first experience
The documentation now has a deliberate reader path:
The previous collection of competing starter applications and entry points has been consolidated around one canonical learning path.
One progressive Ticket Desk tutorial
The primary tutorial now grows one application instead of repeatedly starting over.
It covers:
The final candidate executed the six-stage tutorial with 86 public API assertions against an installed Aksara wheel and PostgreSQL.
Quick Start and onboarding
The first-project experience has been rewritten around the actual scaffold, CLI, configuration, migrations, and generated REST behavior.
A new user can follow one documented route from:
without needing source-code archaeology or internal architecture documents.
Durable Operations as a user-facing capability
v0.7.0 introduced Durable Authorized Operations.
v0.7.1 substantially improves how they are explained.
The documentation now clearly distinguishes:
The user documentation no longer assumes familiarity with ADR 0001 or distributed-systems terminology.
Stable, Evolving, and Experimental boundaries
Capabilities are now much more explicit about maturity.
Stable backend surfaces are separated from evolving and experimental functionality.
In particular, the documentation no longer presents experimental AI, planner, workflow, search, or Studio functionality as if it had the same contract as:
AI remains an optional consumer of the application backend rather than the foundation of the getting-started experience.
Configuration and production guidance
The configuration reference and production manual were substantially revised.
They now distinguish:
The production documentation also makes clearer what Aksara guarantees and what remains the application's or operator's responsibility.
Examples and scaffolding
Repository examples were audited and given explicit roles rather than being treated as equally authoritative starter applications.
The scaffold documentation and CLI instructional text were improved without changing generated runtime behavior.
The final candidate verifies that, after release/version normalization, generated application behavior remains equivalent to v0.7.0 aside from instructional README guidance.
Executable documentation
A major goal of v0.7.1 was to make public documentation testable.
The final release candidate validates:
Public examples are increasingly treated as product surface rather than unverified prose.
Public-truth audit
The v0.7.1 audit corrected 80 documentation contradictions.
These included stale or incorrect claims around areas such as:
The rule throughout the release was:
No runtime feature was added simply to make an old example correct.
Functional findings discovered
The audit also surfaced 22 functional findings.
Those findings remain deliberately unfixed in v0.7.1 because this release preserves a strict no-functional-change boundary.
Examples include issues affecting areas such as:
These are now documented and available for separately reviewed maintenance work.
v0.7.1 does not hide those limitations or quietly change production behavior.
No runtime semantic change
The release scope guard confirms:
Production/package differences from v0.7.0 are limited to:
Validation
The final v0.7.1 candidate passed:
Strict MkDocs builds 162 pages.
42,322 internal links/assets and 41 selected external links were validated.
Ruff and mypy ratchets, Bandit, dependency audit, Gitleaks, Twine, and package validation also passed.
Compatibility
v0.7.1 preserves the runtime contract of v0.7.0.
Existing applications retain the same behavior for:
No new service or runtime dependency is required.
Release artifacts
aksara_framework-0.7.1-py3-none-any.whlSHA-256:
42a3a42be08ee5be1075d4f6da3b22fea6acaa5bf678a57db7ecc00ce4fdd197aksara_framework-0.7.1.tar.gzSHA-256:
d3ce8e4b8c735bfcf61b41f2df90c7cc7a448722e8329b7f074bb9840653cb94v0.7.0 made Aksara's authorized operations durable.
v0.7.1 makes the framework itself substantially easier to understand and evaluate:
This discussion was created from the release Aksara [v0.7.1] — Documentation & Developer Experience.
All reactions