101 lines
5.6 KiB
Markdown
101 lines
5.6 KiB
Markdown
# Libre Study Conventions
|
|
|
|
Libre Study is the desktop-first Bible study application. Its job is to provide a fast, local, searchable, taggable study workspace that can consume normalized Bible and study-resource packages from `libre-bible-data`.
|
|
|
|
## Repository Role
|
|
|
|
- This repo owns the application shell, interface, local storage, search behavior, import behavior, and desktop packaging.
|
|
- This repo does not own source Bible texts, commentaries, maps, lexicons, or study notes.
|
|
- Bible and study resources should enter the app through importable packages generated by `libre-bible-data`.
|
|
- Keep app code and resource data separate unless a tiny fallback seed is needed for development.
|
|
|
|
## Development Workflow
|
|
|
|
- Local development happens in the workspace repo on drive `W:`.
|
|
- The Christ Unscripted Gitea remote is the remote backup, collaboration, and publishing copy.
|
|
- Do not treat work as durable until it is committed locally and pushed to Gitea.
|
|
- Every named implementation phase should bump the app version and be recorded in Git both locally and remotely.
|
|
- Phase completion means the version bump, code/docs changes, and validation result are committed locally and pushed to Gitea.
|
|
- The normal flow is local edit, local verify, local commit, push to Gitea, then publish or release from the pushed state.
|
|
- Do not publish release artifacts from a dirty worktree unless Jason explicitly asks for that exact operation.
|
|
- Keep source-control bookkeeping quiet unless Jason asks about it or a source-control problem affects the work.
|
|
- Use the actual project scripts instead of ad hoc equivalents.
|
|
- Use browser dev mode for fast visual iteration:
|
|
|
|
```powershell
|
|
npm.cmd run dev:web
|
|
```
|
|
|
|
- Use Tauri dev mode when testing native behavior:
|
|
|
|
```powershell
|
|
npm.cmd run dev:tauri
|
|
```
|
|
|
|
- Use packaged builds only when testing installers, app signing, updater behavior, or desktop release behavior.
|
|
- Browser dev mode may use mock/localStorage data. Tauri mode should use the native SQLite-backed commands.
|
|
- If a command starts failing because of PowerShell, Bash, WSL, quoting, heredocs, pipes, regexes, `$` variables, or nested shell layers, stop retrying the same command shape. Move the logic into a script file or use argv-style execution.
|
|
- Prefer PowerShell for normal Windows-local Node/Tauri work in this repo. Use WSL Bash only when a tool or script is genuinely Linux-oriented.
|
|
|
|
## Publishing Model
|
|
|
|
- Gitea is the Git host and backup/publishing surface, not the primary app UI.
|
|
- Public Gitea host: `https://git.christit.com`.
|
|
- Remote URL:
|
|
|
|
```text
|
|
https://git.christit.com/libre-study/libre-study.git
|
|
git@git.christit.com:libre-study/libre-study.git
|
|
```
|
|
|
|
- Public download pages, catalogs, release notes, and package indexes should be generated from repo metadata where possible.
|
|
- Do not hand-maintain public catalog details that can be derived from committed manifests, package catalogs, tags, or releases.
|
|
- Release artifacts should be traceable to a pushed commit.
|
|
- Signed installers and updater metadata should only be produced from intentional release commits.
|
|
- Generated app metadata, package indexes, update manifests, and release notes should be regenerated by scripts rather than hand-corrected after the fact.
|
|
|
|
## Backup Copies
|
|
|
|
- Source control is the main recovery layer, but local `.old` backups are still useful before large, risky, or release-bound edits.
|
|
- Put backups near the affected file or module, not in random temp locations.
|
|
- Prefer backup filenames with timestamp plus short reason, for example `App.tsx.20260712-study-layout.old`.
|
|
- Do not create `.old` backups for every tiny edit. Use them when rollback clarity is worth the extra file.
|
|
|
|
## Changelogs
|
|
|
|
- Keep changelogs newest-first when changelogs are introduced.
|
|
- Use a `## Current` section when helpful, followed by dated release sections.
|
|
- Keep entries concrete and operational: what changed, what behavior was preserved, and what was verified.
|
|
- Mark reconstructed history clearly if it is built from artifacts, old packages, or prior notes.
|
|
|
|
## Data Boundary
|
|
|
|
- The app should import from `libre-bible-data` packages rather than scraping or downloading Bible sources directly.
|
|
- The app should prefer LibreBible machine catalogs over direct file guesses. Catalog paths may come from `LIBREBIBLE_CATALOG_PATH`, a sibling `libre-bible-data` checkout, or later a public ChristIT.com catalog.
|
|
- The local SQLite database is an app cache and user workspace, not the canonical source of public Bible data.
|
|
- User-created tags, highlights, notes, saved searches, layouts, and reading state belong to Libre Study.
|
|
- Translation text, Strong's links, study notes, commentaries, maps, and source metadata belong to `libre-bible-data`.
|
|
|
|
## Product Direction
|
|
|
|
- First target: Windows desktop.
|
|
- First study source: KJV with Strong's-linked data.
|
|
- Core experience: parallel reading, search, tags, notes, highlights, Strong's lookup, and saved study workspaces.
|
|
- Later targets may include macOS, Linux, web/PWA, and mobile, but do not let those future targets compromise the desktop study workflow.
|
|
|
|
## Engineering Rules
|
|
|
|
- Prefer TypeScript for UI and Rust/Tauri commands for native filesystem/database work.
|
|
- Keep UI components decoupled from Tauri `invoke` calls through a client layer so browser dev mode remains usable.
|
|
- Do not hardcode Windows-only paths in app logic unless wrapped behind a platform adapter.
|
|
- Treat installer output as a release artifact, not a normal development artifact.
|
|
- Public release readiness is separate from internal app maturity. A build can be useful for local testing without being ready for public distribution.
|
|
- Run at minimum:
|
|
|
|
```powershell
|
|
npm.cmd run lint
|
|
npm.cmd run build
|
|
```
|
|
|
|
before considering app changes complete.
|