Skip to content

chore: professionalize repo + add SD stress bench + first benchmark results#1

Merged
Vanderhell merged 28 commits into
masterfrom
chore/repo-professionalization
May 11, 2026
Merged

chore: professionalize repo + add SD stress bench + first benchmark results#1
Vanderhell merged 28 commits into
masterfrom
chore/repo-professionalization

Conversation

@Vanderhell
Copy link
Copy Markdown
Owner

@Vanderhell Vanderhell commented May 10, 2026

This PR contains documentation, CI tooling, and packaging changes only.
No source files under src/, include/, port/, or the existing tests/
suite were modified. Public API and build targets are unchanged. The only
new code is non-blocking fuzzing scaffolding under tests/fuzz/.

What changed

  • README rewritten for clarity and trust signals (shorter, technical, no
    marketing-style link farms).
  • Documentation surface cleaned up: process, contract, and product-style
    documents moved to docs/internal/. Single docs index added at
    docs/README.md.
  • Explicit loxdb (MIT, this repo) vs planned loxdb_pro (commercial)
    boundary documented in docs/EDITIONS.md.
  • Benchmark publication template added at docs/BENCHMARKS.md for
    ESP32-S3 N16R8 results (placeholders only; no invented numbers).
  • CI trust-signal scaffolding:
    • Separate ci-coverage-linux preset and coverage job (lcov artifact).
    • Non-blocking clang-tidy lane (cppcheck was already present).
    • Non-blocking nightly fuzz workflow (~10 min runs).
  • Packaging groundwork (not published yet):
    • PlatformIO library.json
    • Arduino library.properties (architectures=esp32)
    • CMake find_package(loxdb) config with loxdb::loxdb namespaced target.

What moved

  • Root community files → .github/ (CODE_OF_CONDUCT, CONTRIBUTING,
    SECURITY, SUPPORT).
  • Release/process and internal status artifacts → docs/internal/.
  • Source boundary docs (ROOT_SPEC_CORE_VS_PRO.md, LOXDB_PRO_BACKLOG.md)
    docs/internal/ after distillation into docs/EDITIONS.md.

What was added

  • docs/TEST_SUITE_SIZE.md documenting the 504 microtest cases across
    48 test files (+1 C++ wrapper test), organized into the existing
    CTest registrations.
  • docs/EDITIONS.md, docs/BENCHMARKS.md, docs/PROFILES.md,
    docs/SAFETY_NOTES.md, docs/README.md.
  • docs/internal/MAINTAINER_TODO.md covering repo settings checklist
    and future CI roadmap (HIL / QEMU lane).
  • tests/fuzz/ scaffolding + minimal WAL parser harness
    (scaffolding only — not yet proven fuzz coverage).
  • library.json, library.properties, cmake/loxdbConfig.cmake.in.

Scope expansion during PR

In addition to the original cleanup, this PR also adds:

  • New SD stress benchmark sketch under bench/loxdb_esp32_s3_sd_stress_bench/
    with admission preflight, fallback ladder, and reinit support
  • First real ESP32-S3 N16R8 benchmark results under docs/results/
    (run on 2026-05-11, commit 4d1fd65)
  • docs/SD_STRESS_BENCH.md documenting the bench harness
  • Social preview banner at docs/social-preview-1280x640.png

What requires maintainer action

See docs/internal/MAINTAINER_TODO.md for the items requiring repo admin
access (GitHub Wiki disable, topics, description, social preview, releases
notes housekeeping, registry publication when ready).

Verification

  • broken_local_links_excl_wiki=0
  • MAINTAINER_AUDIT.md is intentionally not part of this PR
    (working document only; dropped via rebase before push).

@Vanderhell
Copy link
Copy Markdown
Owner Author

TL;DR for reviewers

Scope: documentation, CI tooling, packaging. No source files in src/,
include/, port/, or the existing tests/ were modified.
Public API and build targets are unchanged.

Diff stats: 46 files changed, 786 insertions(+), 416 deletions(-)

Verification:

  • Local markdown link existence check (excluding wiki/ and wiki_repo_sync/):
    broken_local_links_excl_wiki = 0
  • README rewritten and compacted to 77 lines (was ~250).
  • Test count phrasing updated from "175+ tests" to the measured
    "504 microtest cases across 48 test files (+1 C++ wrapper test)".
  • MAINTAINER_AUDIT.md is intentionally absent — working document only,
    dropped via rebase before push (not in history).

File moves (old → new)

Community/governance:

Old New
CODE_OF_CONDUCT.md .github/CODE_OF_CONDUCT.md
CONTRIBUTING.md .github/CONTRIBUTING.md
SECURITY.md .github/SECURITY.md
SUPPORT.md .github/SUPPORT.md

Internal/process artifacts:

Old New
TODO.md docs/internal/TODO.md
RELEASE_LOG.md docs/internal/RELEASE_LOG.md
ROOT_SPEC_CORE_VS_PRO.md docs/internal/ROOT_SPEC_CORE_VS_PRO.md
docs/CHANGE_CYCLE_CHECKLIST.md docs/internal/CHANGE_CYCLE_CHECKLIST.md
docs/DOCS_SYNC_PLAN.md docs/internal/DOCS_SYNC_PLAN.md
docs/FAIL_CODE_CONTRACT.md docs/internal/FAIL_CODE_CONTRACT.md
docs/FOOTPRINT_MIN_CONTRACT.md docs/internal/FOOTPRINT_MIN_CONTRACT.md
docs/LOXDB_PRO_BACKLOG.md docs/internal/LOXDB_PRO_BACKLOG.md
docs/PRODUCT_BRIEF.md docs/internal/PRODUCT_BRIEF.md
docs/PRODUCT_POSITIONING.md docs/internal/PRODUCT_POSITIONING.md
docs/PROFESSIONAL_READINESS.md docs/internal/PROFESSIONAL_READINESS.md
docs/PROFILE_GUARANTEES.md docs/internal/PROFILE_GUARANTEES.md
docs/RELEASE_CHECKLIST.md docs/internal/RELEASE_CHECKLIST.md
docs/RELEASE_TAG_TEMPLATE.md docs/internal/RELEASE_TAG_TEMPLATE.md
docs/SAFETY_READINESS.md docs/internal/SAFETY_READINESS.md
docs/release-notes.md docs/internal/release-notes.md

Suggested review path

If you're short on time, review in this order:

  1. README.md — the most user-visible change.
  2. docs/EDITIONS.md — clarifies what stays MIT and what becomes commercial.
  3. docs/BENCHMARKS.md — placeholder structure for ESP32-S3 N16R8 results.
  4. docs/internal/MAINTAINER_TODO.md — items still requiring repo admin
    access after merge (Wiki disable, topics, description, social preview).

Out of scope (intentionally deferred)

  • Real benchmark numbers in docs/BENCHMARKS.md (will be filled in from
    the ESP32-S3 N16R8 bench runs).
  • WAL-format-aware fuzzing mutators (tests/fuzz/ is scaffolding only).
  • Publication to PlatformIO Registry / Arduino Library Manager
    (manifests are in place; maintainer publishes when ready).
  • Hardware-in-the-loop or QEMU CI lane (tracked in MAINTAINER_TODO).

@Vanderhell Vanderhell changed the title chore: professionalize repository presentation (no API/code changes) chore: professionalize repo + add SD stress bench + first benchmark results May 11, 2026
@Vanderhell Vanderhell marked this pull request as ready for review May 11, 2026 10:31
@Vanderhell Vanderhell merged commit 201bb09 into master May 11, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant