mchus/bible
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Clarify Gitea workflow and ban AI-style unicode markers

Browse Source
This commit is contained in:
Michael Chus
2026-04-22 20:47:27 +03:00
parent 1d89a4918e
commit 472b3e10d9
3 changed files with 53 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
rules/patterns/git-sync-check/contract.md
View File

@@ -3,20 +3,39 @@
## Rule ## Rule
Before starting any work on a task, check whether the remote repository has commits that are not yet present locally. Before starting any work on a task, check whether the remote repository has commits that are not yet present locally.
This rule assumes the repository is hosted in Gitea.
Use neutral `git` commands for sync checks and branch management, and use Gitea terminology for server-side review flow (`pull request`, not `merge request`).
## Required Steps ## Required Steps
1. Run `git fetch` to update remote-tracking refs without merging. 1. Run `git fetch origin` to update remote-tracking refs from the Gitea remote without merging.
2. Check for upstream commits: `git log HEAD..@{u} --oneline`. 2. Check for upstream commits: `git log HEAD..@{u} --oneline`.
3. If the output is non-empty (there are new remote commits): 3. If the output is non-empty (there are new remote commits):
- **Stop immediately. Do not make any changes.** - **Stop immediately. Do not make any changes.**
- Inform the user that the remote has new commits and ask how to proceed (e.g., pull, rebase, or ignore). - Inform the user that the remote has new commits and ask how to proceed (e.g., pull, rebase, or ignore).
4. If the output is empty, proceed with the task normally. 4. If the output is empty, proceed with the task normally.
## Gitea Workflow Notes
- Verify the remote when needed: `git remote -v`
- Create a task branch before changes: `git checkout -b <task-branch>`
- Push the branch to Gitea and set upstream: `git push -u origin <task-branch>`
- Open the review in Gitea as a pull request against the target branch.
- If the `tea` CLI is configured for the environment, it may be used for Gitea pull request actions such as:
- `tea pr list`
- `tea pr create`
- `tea pr checkout <number>`
## Forbidden Assumptions
- Do not assume GitHub-specific tooling such as `gh`.
- Do not use GitLab terminology such as `merge request` unless a project explicitly defines that workflow separately.
- Do not replace the required sync check with web UI inspection in Gitea; the local `git fetch origin` and `git log HEAD..@{u} --oneline` check remains mandatory.
## Rationale ## Rationale
Working on an outdated local state risks merge conflicts, duplicate work, and overwriting changes made by other contributors. Checking remote state first keeps the working tree aligned and prevents avoidable conflicts. Working on an outdated local state risks merge conflicts, duplicate work, and overwriting changes made by other contributors. Checking remote state first keeps the working tree aligned and prevents avoidable conflicts. Using Gitea-specific review terminology and examples also avoids workflow confusion in repositories that are not hosted on GitHub or GitLab.
## Exceptions ## Exceptions
- Offline environments where `git fetch` is not possible: notify the user that the check could not be performed before proceeding. - Offline environments where `git fetch origin` is not possible: notify the user that the check could not be performed before proceeding.

21
rules/patterns/go-code-style/contract.md
View File

@@ -2,6 +2,13 @@
Version: 1.1 Version: 1.1
## Source Text and Comments
- Use plain ASCII in source code and comments by default.
- Do not use em dash, emoji, or other decorative Unicode markers in code, comments, log messages, or user-facing fallback strings unless a feature explicitly requires non-ASCII text.
- Do not leave AI-style markers in the codebase: ornamental phrasing, assistant-like filler, synthetic enthusiasm, or comments that read like generated prose instead of technical documentation.
- Comments must be short, concrete, and technical. Explain intent, invariants, or non-obvious constraints; do not write marketing-style or conversational commentary.
## Logging ## Logging
See `kit/patterns/go-logging/contract.md` for full rules. See `kit/patterns/go-logging/contract.md` for full rules.
@@ -18,7 +25,7 @@ if err := db.Save(&record).Error; err != nil {
return fmt.Errorf("save component %s: %w", record.ID, err) return fmt.Errorf("save component %s: %w", record.ID, err)
} }
// WRONG — loses context // WRONG: loses context
return err return err
``` ```
@@ -35,9 +42,9 @@ return err
Handlers are thin. Business logic belongs in a service layer. Handlers are thin. Business logic belongs in a service layer.
``` ```
Handler → validates input, calls service, writes response Handler -> validates input, calls service, writes response
Service → business logic, calls repository Service -> business logic, calls repository
Repository → SQL queries only, returns domain types Repository -> SQL queries only, returns domain types
``` ```
- Handlers must not contain SQL queries. - Handlers must not contain SQL queries.
@@ -48,7 +55,7 @@ Repository → SQL queries only, returns domain types
``` ```
1. Parse flags / load config 1. Parse flags / load config
2. Connect to DB — fail fast if unavailable (see go-database contract) 2. Connect to DB; fail fast if unavailable (see go-database contract)
3. Run migrations 3. Run migrations
4. Initialize services and background workers 4. Initialize services and background workers
5. Register routes 5. Register routes
@@ -69,14 +76,14 @@ Never reverse steps 2 and 5. Never start serving before migrations complete.
## Template / UI Rendering ## Template / UI Rendering
- Server-rendered HTML via Go templates is the default. - Server-rendered HTML via Go templates is the default.
- htmx for partial updates — no full SPA framework unless explicitly decided. - htmx for partial updates; no full SPA framework unless explicitly decided.
- Template errors must return `500` and log the error server-side. - Template errors must return `500` and log the error server-side.
- Never expose raw Go error messages to the end user in rendered HTML. - Never expose raw Go error messages to the end user in rendered HTML.
## Business Logic Placement ## Business Logic Placement
- Threshold computation, status derivation, and scoring live on the server. - Threshold computation, status derivation, and scoring live on the server.
- The UI only reflects what the server returns — it does not recompute status client-side. - The UI only reflects what the server returns; it does not recompute status client-side.
- Example: "critical / warning / ok" badge color is determined by the handler, not by JS. - Example: "critical / warning / ok" badge color is determined by the handler, not by JS.
## Dependency Rules ## Dependency Rules

33
rules/patterns/go-project-bible/contract.md
View File

@@ -16,29 +16,29 @@ Every project bible must have these files:
``` ```
bible-local/ bible-local/
README.md — index: what files exist and what each covers README.md - index: what files exist and what each covers
architecture/ architecture/
system-overview.md — what the product does, active scope, non-goals system-overview.md - what the product does, active scope, non-goals
data-model.md — domain entities, DB tables, naming conventions data-model.md - domain entities, DB tables, naming conventions
api-surface.md — all HTTP endpoints with methods and response shape api-surface.md - all HTTP endpoints with methods and response shape
runtime-flows.md — key mutation flows, invariants, critical rules runtime-flows.md - key mutation flows, invariants, critical rules
decisions/ decisions/
README.md — ADL format explanation README.md - ADL format explanation
YYYY-MM-DD-topic.md — one file per architectural decision YYYY-MM-DD-topic.md - one file per architectural decision
``` ```
Optional (add when relevant): Optional (add when relevant):
``` ```
architecture/ architecture/
ui-information-architecture.md — page structure, navigation, UI invariants ui-information-architecture.md - page structure, navigation, UI invariants
docs/ docs/
INTEGRATION_GUIDE.md — external system integration (formats, protocols) INTEGRATION_GUIDE.md - external system integration (formats, protocols)
``` ```
## system-overview.md Rules ## system-overview.md Rules
- List what is **in scope** and what is **explicitly out of scope**. - List what is **in scope** and what is **explicitly out of scope**.
- Out of scope section prevents scope creep — update it when you reject a feature. - Out of scope section prevents scope creep; update it when you reject a feature.
- Include tech stack and local run command. - Include tech stack and local run command.
## data-model.md Rules ## data-model.md Rules
@@ -63,7 +63,7 @@ This is the most important file. Document flows that are **easy to break**:
- Event/time source priority rules - Event/time source priority rules
- Deduplication logic - Deduplication logic
- Cross-entity side effects (e.g. removing a component affects asset status) - Cross-entity side effects (e.g. removing a component affects asset status)
- Anything that caused a bug or regression — add a "DO NOT reintroduce" note - Anything that caused a bug or regression: add a "DO NOT reintroduce" note
Format each flow as a numbered list of steps, not prose. Format each flow as a numbered list of steps, not prose.
@@ -94,19 +94,20 @@ What this means going forward. What is now forbidden or required.
``` ```
- One decision per file, named `YYYY-MM-DD-short-topic.md`. - One decision per file, named `YYYY-MM-DD-short-topic.md`.
- When a decision is superseded, add `superseded by` to the old file's status — do not delete it. - When a decision is superseded, add `superseded by` to the old file's status; do not delete it.
- Record the decision **in the same commit** as the code that implements it. - Record the decision **in the same commit** as the code that implements it.
## What NOT to Put in bible-local/ ## What NOT to Put in bible-local/
- Generic rules (CSV format, logging, pagination) → these are in `bible/rules/patterns/` - Generic rules (CSV format, logging, pagination) -> these are in `bible/rules/patterns/`
- Work-in-progress notes, TODO lists → use issues or a separate `docs/` folder - Work-in-progress notes, TODO lists -> use issues or a separate `docs/` folder
- Duplicate of what is already in code (don't restate what the code clearly shows) - Duplicate of what is already in code (don't restate what the code clearly shows)
- Speculative future architecture — document what exists, not what might exist - Speculative future architecture: document what exists, not what might exist
## Keeping the Bible Current ## Keeping the Bible Current
- Update `bible-local/` in the **same commit** as the code change it describes. - Update `bible-local/` in the **same commit** as the code change it describes.
- If you change a flow, update `runtime-flows.md` in the same PR. - If you change a flow, update `runtime-flows.md` in the same PR.
- If a section becomes outdated, fix or delete it — stale docs are worse than no docs. - If a section becomes outdated, fix or delete it; stale docs are worse than no docs.
- Bible files are in **English only**. - Bible files are in **English only**.
- Do not use em dash in Bible files; prefer ASCII punctuation such as `-`, `:`, or `;` depending on the sentence.