docs: bootstrap vault, roadmap and research
This commit is contained in:
@@ -0,0 +1,36 @@
|
||||
# English workflow
|
||||
|
||||
The project documentation is 100% English on purpose: the repo is an immersion environment.
|
||||
Rust is learned through English, English through Rust.
|
||||
|
||||
## Daily habits (zero extra time)
|
||||
|
||||
- **Commit messages in English** — Conventional Commits format forces short, structured sentences.
|
||||
- **DevLog entry** (10 min, last step of every session): 3–5 sentences about what you did,
|
||||
in English. Don't translate from Russian in your head — describe the code, not the feelings.
|
||||
- **Read error messages and docs in English only.** Never switch the compiler or Rust Book to Russian.
|
||||
|
||||
## Weekly habits
|
||||
|
||||
- **One article per sprint** in `articles/` (comparison, tutorial, retro) — reviewed for
|
||||
language quality, not only content. Keep sentences short; prefer active voice.
|
||||
- **Glossary growth**: every new term goes to `learning/glossary.md` with your own example
|
||||
sentence. Re-using a term in your own sentence is what makes it stick.
|
||||
- Weekly self-check: read Monday's DevLog aloud — if you can't, the sentence was too complex.
|
||||
|
||||
## What gets reviewed
|
||||
|
||||
| Artifact | Language focus |
|
||||
|----------|----------------|
|
||||
| Commit messages | imperative mood, conciseness |
|
||||
| DevLog | past simple, describing actions |
|
||||
| Issues / task notes | acceptance criteria phrasing ("must exist when done") |
|
||||
| Articles | structure, connectors, technical vocabulary |
|
||||
| Code comments & rustdoc | explaining "why", not "what" |
|
||||
|
||||
## Rules of thumb
|
||||
|
||||
1. Simple sentences first; compound later. Clarity beats sophistication.
|
||||
2. If you needed a dictionary twice for one sentence — rewrite the sentence, not the vocab.
|
||||
3. Write first, polish after; never let language anxiety stop the log entry.
|
||||
4. Track words you *meet* vs words you *use* — the second list is the real progress.
|
||||
@@ -0,0 +1,40 @@
|
||||
# Gitea workflow
|
||||
|
||||
The project is tracked at **https://git.v-port.ru/vaskes/viexp** (Gitea 1.26.2).
|
||||
CLI access: `tea` (logged in as `vaskes`); API access with the saved token.
|
||||
|
||||
## Verified capabilities (2026-10-17)
|
||||
|
||||
| Feature | Via API? | Notes |
|
||||
|---------|----------|-------|
|
||||
| Labels | ✅ | 11 labels created (`type/*`, `priority/*`, `lang/english`) |
|
||||
| Milestones | ✅ | 13 sprint milestones with due dates |
|
||||
| Issues | ✅ | labels by **ID**, not by name (`POST /repos/vaskes/viexp/issues`) |
|
||||
| Project board (kanban) | ❌ | endpoint missing in Gitea 1.26.2 — create once via web UI |
|
||||
| Actions CI | ✅ | `.gitea/workflows/ci.yml` (repo has `has_actions: true`) |
|
||||
|
||||
## Organization
|
||||
|
||||
- **Project board** ("viexp development", created manually in the web UI):
|
||||
columns `Backlog → In Progress → Review → Done`; sprints are tracked by milestones.
|
||||
- **Milestones** = sprints: `Sprint 0 — Setup & deconstruction` … `Sprint 12 — Release & docs`
|
||||
(one 20-hour sprint ≈ one month at ~45 min/day). Due dates are targets, not deadlines.
|
||||
- **Labels**: `type/bug|feature|docs|research|chore|spike`, `priority/P0…P3`, `lang/english`.
|
||||
- **Issues** are created from task notes (`docs/tasks/`) and sprint definitions-of-done;
|
||||
the task note's `gitea-issue` property stores the issue number.
|
||||
- Bootstrap/repeat script: `scripts/gitea-bootstrap.sh` (labels + milestones + seed issues).
|
||||
|
||||
## Rules
|
||||
|
||||
1. One issue = one demoable outcome; acceptance criteria copied from the task note.
|
||||
2. Branch per issue: `sprint-N/slug` or `feat/slug`; squash-merge into `main`.
|
||||
3. Commit messages: Conventional Commits **in English** (`feat(preview): add kitty graphics support`)
|
||||
— every commit is a micro English exercise.
|
||||
4. An issue is closed only when its acceptance criteria are demoable.
|
||||
5. Sprint retro (from the sprint note) is posted as a comment on the milestone's closing issue.
|
||||
|
||||
## Automation notes
|
||||
|
||||
- Gitea Actions can run `cargo fmt --check && cargo clippy -- -D warnings && cargo test` on push.
|
||||
- Everything set up via API/`tea` is documented in `docs/workflows/` so it can be re-created
|
||||
from scratch (the setup commands are in the sprint-0 task note).
|
||||
@@ -0,0 +1,41 @@
|
||||
# Research workflow
|
||||
|
||||
How research artifacts are collected, analyzed and turned into decisions — the pipeline that
|
||||
feeds every architectural choice in viexp.
|
||||
|
||||
## Lifecycle
|
||||
|
||||
```
|
||||
question → TMP/Research.md note (status: inbox)
|
||||
→ sources collected (table filled)
|
||||
→ findings summarized (status: in-progress)
|
||||
→ synthesis article in articles/ (status: analyzed)
|
||||
→ decision in decisions/ (ADR) + tasks/issues
|
||||
→ archived (status: archived) once superseded
|
||||
```
|
||||
|
||||
1. **Capture.** Any open question gets a `Research` note immediately (title = the question
|
||||
domain, e.g. `djvu-preview-options`). One question per note — small notes beat monoliths.
|
||||
2. **Collect.** Every source goes into the sources table with a one-line takeaway.
|
||||
Screenshots and PDFs go to `attachments/`; paste links, not walls of copied text.
|
||||
3. **Analyze.** Distill findings into bullets; mark `confidence: low|medium|high`.
|
||||
Open questions move to follow-up notes, not into the article.
|
||||
4. **Synthesize.** Cross-note comparisons become `Article` notes (e.g. the file-manager
|
||||
comparison). The article states recommendations, not just facts.
|
||||
5. **Decide.** Every recommendation that changes the architecture becomes an ADR
|
||||
(`Decision` template) — short, dated, linked back to the research notes.
|
||||
6. **Act.** ADRs spawn `Task` notes → Gitea issues (see [[workflows/gitea-workflow|Gitea workflow]]).
|
||||
|
||||
## Weekly review (Friday, 15 min)
|
||||
|
||||
- Process all `status: inbox` notes: promote, merge or archive.
|
||||
- Update ADRs whose status changed during the week.
|
||||
- Check that every active sprint task has a linked issue and vice versa.
|
||||
|
||||
## Obsidian mechanics used
|
||||
|
||||
- **Templates** (`TMP/`) keep structure uniform; headings are predictable, so folding works.
|
||||
- **Properties** (`type`, `status`, `tags`, `sprint`) power the tag pane and search, e.g.
|
||||
`["type": "research", "status": "inbox"]`.
|
||||
- **Backlinks / graph** show which decisions depend on which research.
|
||||
- **Attachments** are centralized in `docs/attachments/` (set in Obsidian settings).
|
||||
Reference in New Issue
Block a user