diff --git a/CHANGELOG.md b/CHANGELOG.md index 2e538f1..206f8af 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,8 @@ -# Changelog +# Disciples Journal Releases + +New changes land under `## Unreleased`; at release time it is renamed by hand to the +version tag (see [docs/build-and-release.md](docs/build-and-release.md)). Each `## ` +header text is **exactly** the release tag (no leading `v`). ## Unreleased diff --git a/CLAUDE.md b/CLAUDE.md index c643f9e..a0b19a7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -52,5 +52,9 @@ change the code, update the matching doc in the same change: - **Add a new reference format or change parsing** → update `docs/reference-formats.md`. - **Introduce a workaround, magic number, or non-obvious behavior** → give it a home: a precise inline comment if local, a `docs/gotchas.md` entry if cross-cutting. -- **Defer something out of scope** → add a `FOLLOWUPS.md` entry; promote it to - `ROADMAP.md` (and a plan doc) if it grows into a real effort. +- **Ship a user-facing change** → add a bullet under `## Unreleased` in `CHANGELOG.md`. +- **Hit a small in-scope tangent** (worth fixing, but it'd derail the current task) → + add a numbered `## N.` section to `FOLLOWUPS.md`, and clear it before the next feature. +- **Plan a new feature or larger effort** → add a numbered `## N.` section to + `ROADMAP.md` (and a plan doc once work starts). `FOLLOWUPS.md` and `ROADMAP.md` serve + different lifespans — don't fold one into the other. diff --git a/FOLLOWUPS.md b/FOLLOWUPS.md index 53949fa..923fc20 100644 --- a/FOLLOWUPS.md +++ b/FOLLOWUPS.md @@ -1,22 +1,28 @@ -# Workspace Follow-Ups +# Follow-ups -Lightweight tracking for tasks identified during other work that weren't tackled in the original scope. These are intentionally deferred — captured here so they don't get lost. +In-scope tangents found while working — important to fix, but they'd derail the task +at hand. Add a numbered `## N.` section below instead of chasing them now, and +**clear these before starting a new feature.** New features and larger efforts go in +[ROADMAP.md](ROADMAP.md), not here. -Add new entries at the top. Remove entries when done (commit message can reference them). +Mark a finished item with a `**Status:** done` line rather than deleting it; completed +items get pruned and the rest renumbered on a periodic cleanup pass. Each entry +carries the repo's standard fields (Identified / What / Why / Context / Effort), where +Effort is sized XS (<1 h) · S (1–4 h) · M (1 day) · L (multi-day). -## Entry format + -Each entry should include: +## 1. Finish pop-out window styling -- **Identified:** YYYY-MM-DD and the work it came up in -- **What:** brief description of the change -- **Why:** the motivation / what value it adds -- **Context:** background, file paths, gotchas, anything that would save the next person 10 minutes of grepping -- **Effort:** rough sizing — XS (<1 h), S (1–4 h), M (1 day), L (multi-day) - ---- - -## Finish pop-out window styling +**Status:** open - **Identified:** 2026-05-31, funky-logic sweep. - **What:** Styles aren't fully ported into freshly created pop-out windows. diff --git a/ROADMAP.md b/ROADMAP.md index d286531..1818c6a 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,20 +1,85 @@ # Roadmap -Larger planned or in-flight efforts. For small deferred findings see +New features and larger planned / in-flight efforts, tracked as numbered `## N.` +sections. For small in-scope tangents to clear before the next feature see [FOLLOWUPS.md](FOLLOWUPS.md); for released history see [CHANGELOG.md](CHANGELOG.md). > Entries below are **observations** about likely directions, inferred from the -> code — not committed plans. Promote one to a real plan/spec doc (and a -> `## Status` section) when work actually starts. +> code — not committed plans. When work actually starts, promote the item to a real +> plan/spec doc and add a `## Status` line here. Mark a shipped item +> `**Status:** done`; prune and renumber on a periodic cleanup pass. -## No efforts currently in flight. +Each item carries a **Lens** (User-facing / Technical health / Growth & ecosystem) +and an **Effort** tag: XS (<1 h) · S (1–4 h) · M (1 day) · L (multi-day). -## Observed future directions +## 1. Multiple Bible versions -- **Multiple Bible versions.** The storage path scheme is already +- **Lens:** User-facing · **Effort:** L +- The storage path scheme is already `//...` and settings expose a "preferred version", but `BookNames`, `ESVApiService`, and rendering assume ESV - end-to-end. Generalizing would mean a version-agnostic content-source seam. -- **A test harness.** There are no automated tests. `BibleReference.parse` (pure, - pattern-heavy, highest-risk logic) is the natural first target. See - [FOLLOWUPS.md](FOLLOWUPS.md). + end-to-end. The headline feature; needs a version-agnostic content-source seam. + +## 2. Bundled offline public-domain version (KJV/WEB) + +- **Lens:** User-facing · **Effort:** M +- Today the plugin is inert without an ESV API token. Shipping a public-domain + translation bundled in the plugin means it works on install with zero setup — a big + onboarding win and a natural first consumer of the multi-version seam (#1). + +## 3. Copy / export passage with attribution + +- **Lens:** User-facing · **Effort:** S +- A "copy passage" action that emits clean markdown/text and auto-appends the required + ESV copyright line. Serves the journaling use case and respects the copyright + obligation noted in `README.md`. + +## 4. Touch / mobile interaction + +- **Lens:** User-facing · **Effort:** M +- `isDesktopOnly` is `false`, but the core interaction is hover-to-preview, which + doesn't exist on touch. Define a tap/long-press affordance so the plugin is actually + usable on mobile. + +## 5. Reading plans / daily reading + +- **Lens:** User-facing · **Effort:** M +- A code block or command that surfaces a day's passage from a plan (e.g. M'Cheyne, + chronological). Leans on existing passage rendering; turns the plugin from a + reference tool into a daily-habit tool. + +## 6. Expand the test harness + +- **Lens:** Technical health · **Effort:** M +- `BibleReference.parse` is covered; extend to `BookNames` normalization, `BibleFiles` + path/filename logic, and the `BibleContentService` resolution funnel + (cache → note → API). The highest-leverage safety net before the multi-version + refactor (#1). See [docs/testing.md](docs/testing.md). + +## 7. Multi-source content seam + +- **Lens:** Technical health · **Effort:** L +- Decouple "where content comes from" from ESV specifically (bible-api.com, local + USFM/USX import, etc.). Pairs with multiple versions (#1) but is the *source* axis + rather than the *version* axis; enables offline import workflows. + +## 8. Rendering robustness: finish pop-out styling + large-passage perf + +- **Lens:** Technical health · **Effort:** M +- Promote the pop-out styling gap tracked in [FOLLOWUPS.md](FOLLOWUPS.md), and address + rendering very long passages (lazy/virtualized render, cache eviction) so whole-book + blocks don't jank. + +## 9. Community plugin store submission + +- **Lens:** Growth & ecosystem · **Effort:** S–M +- The repo already follows `eslint-plugin-obsidianmd` and gates on lint/tests. Getting + listed in Obsidian's community catalog is the single biggest distribution lever and + mostly a compliance/review task. + +## 10. Clickable cross-references & footnotes + +- **Lens:** Growth & ecosystem · **Effort:** M +- The ESV HTML already carries footnotes and cross-references (rendered today as static + text). Making cross-refs clickable to open/preview the target passage turns rendered + passages into a navigable study surface. diff --git a/docs/build-and-release.md b/docs/build-and-release.md index 1333082..cba8b20 100644 --- a/docs/build-and-release.md +++ b/docs/build-and-release.md @@ -31,7 +31,11 @@ The repo follows `eslint-plugin-obsidianmd` (see `eslint.config.mjs`) and the ## Releasing -Releases go through the `justfile` (`just release `), which: +**Before releasing**, rename the `## Unreleased` header in [../CHANGELOG.md](../CHANGELOG.md) +to the version tag — the `justfile` does **not** touch the changelog (it creates the +GitHub release with empty notes), so this promotion is a manual step. + +Releases then go through the `justfile` (`just release `), which: 1. Refuses to run if `git status` is not clean. 2. Runs `npm test` — a failing test aborts the release before any files are mutated. @@ -39,7 +43,7 @@ Releases go through the `justfile` (`just release `), which: 5. Builds with `npm run build-no-check`. 6. Commits (`Prepares for release ''`) and pushes. 7. Creates a GitHub release with `gh`, uploading `main.js`, `manifest.json`, and - `styles.css` as assets. + `styles.css` as assets (release notes are left empty — the changelog is the record). ### gh token note