chore: move docs/plans/specs to main repo
This commit is contained in:
@@ -1,136 +0,0 @@
|
||||
# Bugs & Fixes
|
||||
|
||||
Backlog of confirmed bugs with root cause analysis and implementation spec for the fix.
|
||||
|
||||
---
|
||||
|
||||
## BUG-001 — New entry not visible after form submission
|
||||
|
||||
**Status:** fixed 2026-06-18
|
||||
**Reported:** 2026-06-18
|
||||
|
||||
### Symptom
|
||||
|
||||
After submitting a new post via `/post`, the entry page file is created correctly on disk but does not appear in the `/tracker` feed or in the Grav Admin panel until the cache is manually flushed.
|
||||
|
||||
### Root cause
|
||||
|
||||
Grav's page-tree cache (`cache/doctrine/`) is not invalidated when `add-page-by-form` writes a new page to disk. The tracker template uses `page.children`, which Grav serves from cache — so the new child page is invisible until the cache is cleared.
|
||||
|
||||
### Workaround (manual)
|
||||
|
||||
Run in terminal after each submission:
|
||||
|
||||
```bash
|
||||
docker exec intotheeast_grav bash -c "cd /app/www/public && php bin/grav clearcache"
|
||||
```
|
||||
|
||||
### Fix spec
|
||||
|
||||
Wire cache-clear into the form process so it happens automatically on every successful submission.
|
||||
|
||||
**Approach — custom Grav plugin event hook:**
|
||||
|
||||
1. Create a small plugin `user/plugins/cache-on-save/` with one event listener:
|
||||
- Listen on `onFormProcessed`
|
||||
- When the form name is `new-entry`, call `$this->grav['cache']->deleteAll()` (note: `clear()` does not exist on `Grav\Common\Cache` in Grav 1.7)
|
||||
2. Enable the plugin in `user/config/plugins/cache-on-save.yaml`
|
||||
|
||||
This is the cleanest approach: it fires exactly once per successful submission, requires no changes to `post-form.md`, and works for any future forms too.
|
||||
|
||||
**Alternative — disable page cache entirely:**
|
||||
|
||||
Set `cache: { enabled: false }` in `system.yaml`. Simpler but degrades frontend performance; not recommended for production.
|
||||
|
||||
### Files to create/modify
|
||||
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
| `user/plugins/cache-on-save/cache-on-save.php` | New plugin, ~30 lines |
|
||||
| `user/plugins/cache-on-save/cache-on-save.yaml` | Plugin manifest, enabled: true |
|
||||
| `user/config/plugins/cache-on-save.yaml` | Runtime config, enabled: true |
|
||||
|
||||
### Acceptance criteria
|
||||
|
||||
1. Submit a new post via `/post`
|
||||
2. Navigate to `/tracker` — the new entry is visible immediately, no manual cache flush needed
|
||||
3. Grav Admin also shows the new page immediately
|
||||
|
||||
---
|
||||
|
||||
## BUG-002 — Stale Twig cache after theme file changes
|
||||
|
||||
**Status:** fixed 2026-06-18
|
||||
**Reported:** 2026-06-18
|
||||
|
||||
### Symptom
|
||||
|
||||
After theme template files are added or modified (e.g., creating `partials/base.html.twig`), Grav's Twig compiled-template cache still holds the old compiled version. Pages that extend the changed file throw 500 errors like "Template partials/base.html.twig is not defined" even though the file exists on disk.
|
||||
|
||||
### Root cause
|
||||
|
||||
Grav caches compiled Twig templates in `cache/twig/`. When a new file is added, existing templates that reference it don't know to recompile — their cache entries are still valid from their own mtime perspective.
|
||||
|
||||
### Workaround (manual)
|
||||
|
||||
Run after any theme file is added or changed:
|
||||
|
||||
```bash
|
||||
docker exec intotheeast_grav bash -c "cd /app/www/public && php bin/grav clearcache"
|
||||
```
|
||||
|
||||
### Fix spec
|
||||
|
||||
Disable Twig template caching in development via `user/config/system.yaml`:
|
||||
|
||||
```yaml
|
||||
twig:
|
||||
cache: false
|
||||
```
|
||||
|
||||
Acceptable for a single-user dev setup — eliminates both BUG-001's side-effect and this bug entirely. Performance cost is negligible at one-user scale. On production, leave Twig cache enabled (it's fine there because template files don't change at runtime).
|
||||
|
||||
**Files to change:**
|
||||
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
| `user/config/system.yaml` | Add `twig: { cache: false }` under development section |
|
||||
|
||||
### Acceptance criteria
|
||||
|
||||
1. Add a new theme template file
|
||||
2. Reload any page — no 500 error, template works immediately without manual cache flush
|
||||
|
||||
---
|
||||
|
||||
## BUG-003 — One post per day limit; silent failure on duplicate date
|
||||
|
||||
**Status:** fixed 2026-06-18
|
||||
**Reported:** 2026-06-18
|
||||
|
||||
### Symptom
|
||||
|
||||
Submitting a second post with the same date as an existing entry shows "Entry posted successfully!" but creates no file. The user's post is silently discarded.
|
||||
|
||||
### Root cause
|
||||
|
||||
The `add-page-by-form` plugin built the page slug from date only (`Y-m-d`), producing folder names like `2026-06-18.entry`. With `overwrite_mode: false`, if that folder already exists the plugin skips page creation but does not abort — the `message` process step runs regardless, showing a false success.
|
||||
|
||||
### Fix
|
||||
|
||||
Change the slug template in `user/pages/02.post/post-form.md` to include time and title:
|
||||
|
||||
```twig
|
||||
{{ form.value.date|date('Y-m-d-Hi') }}-{{ form.value.title|lower|regex_replace('/[^a-z0-9]+/', '-')|trim('-') }}
|
||||
```
|
||||
|
||||
Example: title "Arrived in Tokyo" at 14:30 on 2026-06-18 → `2026-06-18-1430-arrived-in-tokyo`
|
||||
|
||||
The slug is locked at creation time. Renaming the title afterwards does not change the URL.
|
||||
|
||||
### Acceptance criteria
|
||||
|
||||
1. Submit two posts on the same day with different times or titles — both appear in `/tracker` as separate entries
|
||||
2. Renaming a post's title in the frontmatter does not break its URL
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user