Skip to content

README.md

Latest commit

 

History

History
117 lines (102 loc) · 6.36 KB

README.md

File metadata and controls

117 lines (102 loc) · 6.36 KB

Base Documentation

This directory holds design, architecture, and operational documentation for Base. The top-level README is the product front door, and FAQ.md answers common first-run and product questions. This page is the documentation map.

For contribution workflow, branch naming, tests, and PR expectations, see CONTRIBUTING.md.

For GitHub labels, milestones, Projects, issue assignment, branch names, and worktree-based PR trains, see GitHub Workflow.

For release preparation, tagging, GitHub Releases, and the Homebrew tap update, see Release Process.

For self-guided or live walkthrough material, see Presentations.

Naming Convention

Use stable topic names for documentation files:

  • architecture.md for the broad product and system architecture.
  • <feature>.md for focused feature designs such as ide-bootstrapping.md.
  • <domain>-<topic>.md when a shorter topic name would be ambiguous.
  • Avoid generic names such as design.md once the subject is known.

Document titles can still say whether a page is a design, model, boundary, or reference. The filename should answer "what is this about?"

Core Documents

  • Why Base is the concise evaluator page for why Base exists, what it gives a multi-repo workspace, and how it compares with adjacent developer-environment tools.
  • Product Assessment records the maintained assessment of Base's originality, usefulness, adoption potential, and creator/engineering skill evidence.
  • Command Quick Reference is the one-page lookup table for the current basectl command surface and important flags.
  • Technical Overview is the scannable product and technical reference: workspace shape, tech stack, three-layer architecture, manifest contract, command tables, and file locations.
  • Architecture describes Base's product direction, command model, environment model, manifest shape, and repository conventions.
  • First-Mile Bootstrap documents bootstrap.sh, install mode selection, handoff commands, and contributor setup.
  • Clean macOS Install Validation defines the repeatable Homebrew and source checkout validation checklist.
  • Execution Model documents the current basectl runtime, dispatch order, public launchers, and runtime shell behavior.
  • Linux Support defines the first Ubuntu/Debian runtime support plan and bootstrap boundaries.
  • Runtime Environment is the canonical reference for Base-managed environment variables, ~/.baserc, and mutability rules.
  • Local Observability defines the future local command history, last-error explanation, and report model beyond raw runtime logs.
  • Release Process defines the Base release ceremony, version-file policy, GitHub Release flow, and Homebrew tap follow-up.
  • Homebrew Upgrade Rehearsal defines the pre-1.0.0 consumer upgrade proof and records rehearsal results.
  • Testing explains Base's Python, BATS, and hermetic integration test layers.
  • Tool Boundaries records ecosystem decisions for tools such as mise, direnv, Homebrew, IDEs, Docker, and dotfile managers.

Presentations

Feature And Boundary Documents

  • IDE Bootstrapping covers project IDE manifests, supported IDEs, extensions, additive settings, and diagnostics.
  • Local Config covers user-local Base config, precedence, sync guidance, and the user/project boundary.
  • Project Installers defines how project-owned installers should use Base without moving product-specific logic into Base.
  • Artifact Adapter Registry designs the declarative registry and adapter boundary for Base-managed artifacts.
  • Python Manifest Section records the future structured Python manifest shape and its relationship to current python-package artifacts.
  • Repository Baseline documents basectl repo init, basectl repo check, basectl repo configure, and the optional basectl repo agent-guidance layer for standardizing new Base-managed repositories.
  • Remote Installer Policy defines the allowed remote shell installer URLs, opt-in boundaries, dry-run behavior, and logging expectations for setup paths.
  • Workspace Manifest defines the local team-shared repo-set contract and basectl workspace --manifest reporting behavior.
  • Setup Hooks Boundary records why Base does not support arbitrary manifest setup hooks yet.
  • basectl onboard captures the guided setup experience and its relationship to project installers.
  • basectl ci defines the non-interactive CI entry point and its relationship to Linux runtime support.
  • basectl check parallelism records the evaluation and implementation constraints for parallel check probes.
  • Doctor Finding IDs is the stable reference for BASE-D*, BASE-P*, BASE-H*, and BASE-W* finding identifiers emitted by basectl doctor --format json.
  • Base-managed demo project defines the proof project criteria for showing Base's complete workspace workflow.
  • Project Demo Workflow documents demo.script, basectl demo, Base's self-demo, and the base-demo reference repository.
  • Demo Maintenance defines the needs-demo label and PR convention for keeping executable demos aligned with product changes.
  • base_cli Runtime Package describes the Python CLI foundation used by Base and Base-supported project CLIs.
  • GitHub Workflow documents how Base uses GitHub Issues, labels, milestones, Projects, worktrees, and PR trains.