55 lines
2.6 KiB
Markdown
55 lines
2.6 KiB
Markdown
# Instructions for the Thinkloom development log
|
|
|
|
These instructions supplement `.labyricorn/AGENTS.md` and apply to the
|
|
`devlog/` directory.
|
|
|
|
## Index and entry structure
|
|
|
|
- Keep the devlog index at `devlog/contents.lr` using `_model: devlog`.
|
|
- Store each published entry at `devlog/<stable-slug>/contents.lr` using
|
|
`_model: devlog-entry`.
|
|
- Use a lowercase hyphenated directory name that describes the milestone. The
|
|
directory name becomes part of the public URL and must remain stable.
|
|
- Every entry must include `schema_version`, `title`, `date`, `author`,
|
|
`summary`, `tags`, `source_commit`, and `body`.
|
|
- Set `source_commit` to the full 40-character commit ID most directly
|
|
associated with the entry. Confirm that it resolves in this repository.
|
|
- Use the commit's actual calendar date for retrospective entries. Do not use
|
|
the date on which the devlog prose was written.
|
|
|
|
## Editorial guidance
|
|
|
|
- Base retrospective entries on verifiable repository history, existing project
|
|
documents, and implemented behavior.
|
|
- Do not invent motivations, conversations, results, release status, user
|
|
feedback, or completion claims.
|
|
- A devlog should explain the milestone, why it mattered, and what changed. It
|
|
should not merely expand a commit message or enumerate every changed file.
|
|
- Distinguish a design or schema contract from a completed runtime
|
|
implementation.
|
|
- Keep one main milestone per entry. Link to the relevant canonical commit using
|
|
the Gitea HTTPS URL.
|
|
- Write summaries that work in chronological listings without requiring the
|
|
reader to open the entry.
|
|
- Use focused tags consistently; avoid creating capitalization or spelling
|
|
variants of an existing tag without a reason.
|
|
|
|
## Chronology and lifecycle
|
|
|
|
- The Labyricorn site orders entries by `date` and provides links back to the
|
|
project and to older/newer entries. Do not add manual next/previous links.
|
|
- Multiple entries may share a date; ordering ties should be resolved by the
|
|
importer from source history rather than invented timestamps in prose.
|
|
- Do not rewrite old entries merely because the implementation later changed.
|
|
Add a new entry or a clearly labelled correction when historical context is
|
|
needed.
|
|
- Do not delete or rename a published entry without explicit approval and a
|
|
redirect or archival decision for its existing URL.
|
|
|
|
## Review requirements
|
|
|
|
- Verify the entry date and `source_commit` against `git log`.
|
|
- Check that the source-commit link targets the same full commit ID.
|
|
- Check prose against the referenced commit and current documentation.
|
|
- Parse the record with Lektor and run `git diff --check` before committing.
|