187 lines
4.9 KiB
Markdown
187 lines
4.9 KiB
Markdown
# Trainlog Development Contract
|
|
|
|
## 1. Scope
|
|
|
|
Trainlog is composed of two applications sharing a versioned exchange format:
|
|
|
|
- a lightweight Android application for fast workout data entry;
|
|
- a Unix/Linux TUI for storage, review, analysis, and visualization.
|
|
|
|
The TUI SQLite database is the canonical long-term history.
|
|
|
|
JSON files are the exchange contract between Android and the TUI.
|
|
|
|
## 2. General development rules
|
|
|
|
Every change must respect the following rules:
|
|
|
|
1. behavior is defined before implementation;
|
|
2. code must be readable and deterministic;
|
|
3. errors must be handled explicitly;
|
|
4. user data must never be silently discarded;
|
|
5. persistent formats must be versioned;
|
|
6. importing the same data repeatedly must not create duplicates;
|
|
7. every new feature must be documented;
|
|
8. affected tests must be added or updated;
|
|
9. compiler warnings are treated as defects unless explicitly justified;
|
|
10. an undocumented or untested feature is not considered complete.
|
|
|
|
## 3. TUI
|
|
|
|
The TUI is implemented in C17.
|
|
|
|
Planned dependencies:
|
|
|
|
- ncursesw;
|
|
- SQLite3;
|
|
- a deliberately selected JSON library;
|
|
- Meson;
|
|
- Ninja.
|
|
|
|
The business logic, persistence layer, and ncurses rendering layer must remain separated.
|
|
|
|
SQLite calls must not be scattered through rendering code.
|
|
|
|
Important business rules must not depend directly on ncurses.
|
|
|
|
## 4. Android
|
|
|
|
The Android application is a data-entry client.
|
|
|
|
It must remain intentionally simple and must not become the primary analytics or historical store.
|
|
|
|
It must support:
|
|
|
|
- starting a workout session;
|
|
- automatic recording of the start time;
|
|
- selecting or creating an exercise;
|
|
- entering planned sets and repetitions;
|
|
- entering actual sets and repetitions;
|
|
- entering load;
|
|
- entering planned rest time;
|
|
- entering body weight and supported measurements;
|
|
- automatic recording of the end time;
|
|
- exporting a valid Trainlog JSON file.
|
|
|
|
## 5. Documentation
|
|
|
|
Documentation is mandatory.
|
|
|
|
Primary documents:
|
|
|
|
- `README.md`: user-facing project overview;
|
|
- `docs/architecture.md`: architecture and component boundaries;
|
|
- `docs/coding_style.md`: coding and commenting conventions;
|
|
- `docs/exchange_format.md`: JSON exchange contract;
|
|
- `docs/database.md`: SQLite schema and migration policy;
|
|
- `docs/tui.md`: TUI behavior and visual rules;
|
|
- `docs/android.md`: Android behavior and scope;
|
|
- `docs/tests.md`: validation strategy and commands;
|
|
- `docs/roadmap.md`: implementation order and gates.
|
|
|
|
A behavior change must update the relevant documentation in the same change.
|
|
|
|
## 6. Code comments
|
|
|
|
Comments are mandatory when code expresses:
|
|
|
|
- an invariant;
|
|
- a format constraint;
|
|
- an architectural decision;
|
|
- non-obvious logic;
|
|
- special error handling;
|
|
- a public API;
|
|
- an important data structure;
|
|
- an assumption required for correctness.
|
|
|
|
Comments must not merely restate obvious code.
|
|
|
|
Prefer explaining why a decision exists when the reason is not obvious from the code.
|
|
|
|
## 7. Exchange format
|
|
|
|
The Trainlog format is versioned.
|
|
|
|
Each workout export must contain:
|
|
|
|
- a format identifier;
|
|
- a schema version;
|
|
- a unique session identifier;
|
|
- ISO 8601 timestamps including an explicit UTC offset.
|
|
|
|
Exercise identifiers are stable and permanent.
|
|
|
|
An exercise display name may change without changing its identifier.
|
|
|
|
Imports must be idempotent.
|
|
|
|
A published format version must never receive an incompatible semantic change.
|
|
|
|
## 8. TUI visual rules
|
|
|
|
The TUI uses color when it improves understanding.
|
|
|
|
Color must never be the sole carrier of information.
|
|
|
|
Important states must remain understandable in monochrome terminals.
|
|
|
|
Colors must be centralized in a dedicated theme module.
|
|
|
|
The TUI must use `ncursesw` and handle UTF-8 correctly.
|
|
|
|
Raw ANSI escape sequences are forbidden in ncurses rendering code unless explicitly documented and justified.
|
|
|
|
## 9. Database
|
|
|
|
SQLite is the canonical TUI store.
|
|
|
|
The database schema must be versioned.
|
|
|
|
Incompatible schema evolution requires an explicit migration.
|
|
|
|
Integrity constraints must be used where appropriate, including:
|
|
|
|
- foreign keys;
|
|
- unique identifiers;
|
|
- anti-duplication constraints.
|
|
|
|
## 10. Validation
|
|
|
|
Before every meaningful push:
|
|
|
|
- build;
|
|
- run tests;
|
|
- verify formatting;
|
|
- verify compiler warnings;
|
|
- validate JSON examples against the schema;
|
|
- verify documentation impacted by the change.
|
|
|
|
The repository must not knowingly be pushed in a broken state.
|
|
|
|
## 11. Git workflow
|
|
|
|
Forgejo is the primary repository.
|
|
|
|
Primary remote:
|
|
|
|
`ssh://git@git.labfytools.com:2223/fy59/trainlog.git`
|
|
|
|
GitHub is a mirror:
|
|
|
|
`git@github.com:labfytools/trainlog.git`
|
|
|
|
Normal development must push to Forgejo.
|
|
|
|
Do not develop directly against the GitHub mirror.
|
|
|
|
## 12. Definition of Done
|
|
|
|
A task is complete only when:
|
|
|
|
- the expected behavior is implemented;
|
|
- the code builds without accepted warnings;
|
|
- relevant tests pass;
|
|
- new error paths are handled;
|
|
- documentation is current;
|
|
- examples and schemas are updated when required;
|
|
- no known regression is intentionally left behind.
|