Laurence
031074c9a9
Bootstrap of the project (M0). Sets up the monorepo, design docs, hardware BOM, the open API contract, component skeletons, licensing and CI, following the Default Workflow SOP. What changed: - CLAUDE.md + docs/: copied the Default Workflow so sessions load the SOP. - state/: PROJECT, ARCHITECTURE, DECISIONS, TODO, NOTES filled in for OpenScribe. ARCHITECTURE captures the four-part design (firmware, server, app, case) and the three sync paths; DECISIONS records the hardware, AI-stack, storage, app and licensing choices; TODO lays out milestones M1-M9. - hardware/BOM.md: two build options (compact XIAO ESP32-S3 Sense; dev ESP32-S3 + I2S mic + SD), wiring/pinout, indicative cost. - api/openapi.yaml: the completely open API (device + server surfaces), including recording list/download/delete and exports (wav/ogg/txt/srt/vtt/md/json). - firmware/: PlatformIO ESP32-S3 project, two board profiles, pin map, boot scaffold with module seams for M1-M4. - server/: FastAPI skeleton mirroring the OpenAPI, config for self-hosted MinIO, faster-whisper and Ollama; stub routes browsable at /docs. - app/, case/: Flutter app plan; parametric OpenSCAD enclosure. - Licensing: GPL-3.0 (code), CERN-OHL-S-2.0 (hardware), CC-BY-SA-4.0 (case/docs), REUSE-style LICENSES/ with SPDX headers; LICENSING.md explains the split. - CI: Forgejo Actions workflow builds firmware (both profiles) and lints/imports server. Why: - Everything self-hosted and openly licensed per the user's requirements: an open API, three sync paths (BLE control, WiFi transfer, independent WiFi upload on charge to generic cloud storage), and a full self-hosted transcription+summary stack. Notes: - No custom PCB in v1; off-the-shelf modules. Physical verification waits on parts. - Component code is stubs at M0; features land milestone by milestone, each as its own branch/PR per the workflow. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
76 lines
2.4 KiB
Markdown
76 lines
2.4 KiB
Markdown
# Workflow
|
|
|
|
The branch, commit, PR and merge process for every feature. A "feature" is any unit of
|
|
change: a new capability, a fix, a refactor.
|
|
|
|
## 1. Branch per feature
|
|
|
|
Never build directly on the trunk. Start each feature from an up to date trunk:
|
|
|
|
```
|
|
git checkout main
|
|
git pull
|
|
git checkout -b feature/<short-kebab-description>
|
|
```
|
|
|
|
Use a clear prefix: `feature/`, `fix/`, `refactor/`, `docs/`.
|
|
|
|
## 2. Commit with full notes
|
|
|
|
Commit in logical steps, not one giant dump at the end. Every commit message carries
|
|
the full record of what changed and why, because the commit history is the primary
|
|
source a later documentation session reads.
|
|
|
|
Message shape:
|
|
|
|
```
|
|
<type>: <concise summary in the imperative>
|
|
|
|
What changed:
|
|
- <file or area>: <what and why>
|
|
- ...
|
|
|
|
Why:
|
|
- <the reasoning, constraints, or decision behind the change>
|
|
|
|
Notes:
|
|
- <anything a cold session should know: trade-offs, follow-ups, gotchas>
|
|
```
|
|
|
|
Do not write "written by Claude" in code or messages. If the project convention
|
|
requires an authorship tag (for example `ai:claude`), follow that project's rule.
|
|
|
|
## 3. Keep state files current
|
|
|
|
As you work, update `state/TODO.md` and `state/DECISIONS.md`. Decisions go in the log
|
|
with a date and rationale. This is what lets the next session skip the chat history.
|
|
|
|
## 4. Open a PR when the feature is complete
|
|
|
|
When the feature is done and self consistent, push the branch and open a PR. The PR
|
|
description is the human and machine readable summary of the feature. Use the template
|
|
in `templates/PR_TEMPLATE.md`. It must state:
|
|
|
|
- **Feature** - what was built, in plain terms.
|
|
- **What was achieved** - the outcome, and how to verify it.
|
|
- **Tools used** - languages, libraries, commands, services involved.
|
|
- **How it works** - enough for a documentation session to start from the PR alone.
|
|
- **Follow ups** - anything deferred.
|
|
|
|
## 5. Merge into the trunk
|
|
|
|
Merge the PR into the trunk once it is complete. Prefer a merge that preserves the
|
|
commit history (the notes in each commit are valuable). Delete the feature branch after
|
|
merge.
|
|
|
|
## 6. Do not document in this session
|
|
|
|
Writing the user facing documentation is a separate job, done in a separate session,
|
|
against the merged history. See [Documentation policy](documentation-policy.md). Your
|
|
job in the building session ends at a merged, well commented, well described feature.
|
|
|
|
## Summary
|
|
|
|
```
|
|
branch -> commit (full notes) -> update state/ -> PR (feature, tools, outcome) -> merge -> stop
|
|
```
|