Fix documentation inconsistencies and bump document versions
This commit is contained in:
Jan Doubravský
@@ -0,0 +1,79 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to this documentation repository, grouped by version and release date.
|
||||
Document versions of the individual guideline files are tracked separately in their headers.
|
||||
|
||||
## 0.4.0 — 2026-08-18
|
||||
|
||||
### Added
|
||||
- Skill versioning: every `SKILL.md` now carries `metadata.version` — `changelog` v2, `check` v1,
|
||||
`commit` v2, `documentation` v1, `documentation_context` v2. The skill format has no top-level
|
||||
`version` field; `metadata` is one of the six Agent Skills spec fields, so the frontmatter still
|
||||
packages and uploads cleanly
|
||||
- "Skills" section in `README.md` describing the versioning convention, the install location
|
||||
(`~/.claude/skills/`) and the rule that the folder name — not `name:` — is the command
|
||||
- The five skills listed individually in the `README.md` structure tree
|
||||
- `AGENTS.md` v5 → v6: new "Commit messages" subsection under Git — commits and pull requests must
|
||||
never carry AI authorship (`Co-Authored-By`, "Generated with …", tool signatures or emoji footers).
|
||||
The subsection also states the single-line verbal English style, so assistants without the `commit`
|
||||
skill get the same rules; the AI-authorship rule was added to the skill as well
|
||||
- `CHANGELOG.md` for this repository, with history backfilled from the git log
|
||||
- Explicit line length for Rust: 100 characters (rustfmt default `max_width`) in both Rust design documents
|
||||
- `README.md`, `docs/`, `prebuild.py` and the PyInstaller `.spec` to the template structure in `Python/TEMPLATE.md`
|
||||
- Note in `Python/TEMPLATE.md` that `AGENTS.md` and `DESIGN_DOCUMENT.md` are not part of the template
|
||||
- `README.md` to the session read list in `Claude/CLAUDE.md`, plus a missing top-level heading
|
||||
|
||||
### Changed
|
||||
- Document versions bumped for the structural changes released on 2026-08-18:
|
||||
`DESIGN_DOCUMENT.md` v8 → v9, `DESIGN_DOCUMENT_MODULE.md` v1 → v2,
|
||||
`Rust/DESIGN_DOCUMENT.md` v1 → v2, `Rust/DESIGN_DOCUMENT_LIB.md` v1 → v2,
|
||||
`DESIGN_DOCUMENT_GODOT.md` v1 → v2
|
||||
- `Project template/CHANGELOG.md` now names the project manifest generically
|
||||
(`pyproject.toml`, `Cargo.toml`, `project.godot`) instead of `pyproject.toml` only
|
||||
- Godot debug constant renamed `Constants.DEBUG` → `Constants.DEFAULT_DEBUG`, matching the Python reference module
|
||||
- `README.md` step 1 of "Starting a new project" now also requires writing a `README.md`
|
||||
- `Python/TEMPLATE.md` entry point is named by purpose or tool name instead of `main.py`
|
||||
- `prebuild.py` loads `.env` before importing `src.constants` instead of relying on the import side effect
|
||||
|
||||
### Fixed
|
||||
- Skill folder `Claude/skills/context/` renamed to `documentation_context/`, with the frontmatter
|
||||
`name` matched to it. The folder name is what Claude Code turns into the command, so the old
|
||||
mismatch meant installing from this repository would have changed `/documentation_context`
|
||||
into `/context`
|
||||
- Removed the misplaced lock-file rule from the Testing sections of `DESIGN_DOCUMENT_MODULE.md` (§9)
|
||||
and `Rust/DESIGN_DOCUMENT_LIB.md` (§8) — it already belongs to the Poetry / Distribution sections
|
||||
|
||||
## 0.3.0 — 2026-08-18
|
||||
|
||||
### Added
|
||||
- `Zscaler/ZSCALER_CERTIFICATE.md` — full certificate setup for Node, Python, git and cargo
|
||||
- Language-specific `.gitignore` files for Python, Rust and Godot, plus a shared core in `Project template/`
|
||||
- `poetry.lock` and `prebuild.py` sections in `Python/DESIGN_DOCUMENT.md`
|
||||
|
||||
### Changed
|
||||
- Unified task notation across all languages on the Todo Tree tags `TODO`, `FIXME`, `BUG`, `HACK`, `NOTE`
|
||||
- `AGENTS.md` v4 → v5: rewritten as strictly language-agnostic, naming no concrete tool
|
||||
- Python line length 150 → 120 characters
|
||||
- Rust edition 2021 → 2024 (requires Rust 1.85 or newer)
|
||||
- Godot project version key corrected to `application/config/version`
|
||||
- Every design document now lists `README.md` among the core root documents
|
||||
|
||||
### Removed
|
||||
- `Zscaler/NODE_EXTRA_CA_CERTS.md`, superseded by `ZSCALER_CERTIFICATE.md`
|
||||
|
||||
## 0.2.0 — 2026-06-24
|
||||
|
||||
### Added
|
||||
- `Godot/DESIGN_DOCUMENT_GODOT.md` — Godot development guidelines (v1)
|
||||
|
||||
## 0.1.0 — 2026-05-25
|
||||
|
||||
### Added
|
||||
- `Rust/DESIGN_DOCUMENT.md` and `Rust/DESIGN_DOCUMENT_LIB.md` — Rust guidelines for applications and libraries (v1)
|
||||
- `Claude/` — `CLAUDE.md`, `AGENTS.md` (v4) and the custom skills `changelog`, `check`, `commit`, `context`, `documentation`
|
||||
- `Python/` — `DESIGN_DOCUMENT.md` (v8), `DESIGN_DOCUMENT_MODULE.md` (v1), `TEMPLATE.md`, and the reference `constants.py` module with tests
|
||||
- `Project template/` — `PROJECT.md` and `CHANGELOG.md` templates
|
||||
|
||||
### Changed
|
||||
- Documentation organised into topic folders: `Claude/`, `Python/`, `Zscaler/`, `Project template/`
|
||||
- `README.md` rewritten to describe the repository itself instead of a single project
|
||||
+8
-1
@@ -1,6 +1,6 @@
|
||||
# AI Agents - Project Rules
|
||||
|
||||
**Document Version:** v5 (independent, incremented on structural changes)
|
||||
**Document Version:** v6 (independent, incremented on structural changes)
|
||||
|
||||
Language-agnostic rules for AI assistants (Claude Code, Cursor, Copilot, etc.).
|
||||
|
||||
@@ -68,6 +68,13 @@ Where this file and a design document disagree, **the design document wins**.
|
||||
- **Never commit shared documentation** (`AGENTS.md`, `DESIGN_DOCUMENT*.md`) — it comes from the documentation repository, not from the project
|
||||
- `README.md`, `PROJECT.md` and `CHANGELOG.md` **are committed** — they are project-specific
|
||||
|
||||
### Commit messages
|
||||
|
||||
- **Never sign commits with AI authorship** — no `Co-Authored-By: Claude` (or any other assistant), no "Generated with …" line, no tool name or emoji footer. The same applies to pull request descriptions and issue comments.
|
||||
- The commit author is the human running the tool; the message describes the change, nothing else
|
||||
- Single-line verbal style — "Add X", "Fix Y", "Refactor Z" — never a filename-style message
|
||||
- Written in English
|
||||
|
||||
## Versioning
|
||||
|
||||
- Follow semantic versioning (MAJOR.MINOR.PATCH)
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
# CLAUDE.md
|
||||
|
||||
## First-time setup
|
||||
|
||||
**At the start of every new session, read all of the following files before doing anything else:**
|
||||
|
||||
- `CLAUDE.md` (this file)
|
||||
- `README.md`
|
||||
- `AGENTS.md`
|
||||
- `PROJECT.md`
|
||||
- `CHANGELOG.md`
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
---
|
||||
name: changelog
|
||||
description: Updates changelog in project
|
||||
metadata:
|
||||
version: v2
|
||||
---
|
||||
|
||||
Take known info and make changes to CHANGELOG.md to make them up-to-date.
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
---
|
||||
name: check
|
||||
description: Check for failed tests
|
||||
metadata:
|
||||
version: v1
|
||||
---
|
||||
Try running tests and investigate failed results
|
||||
@@ -1,6 +1,8 @@
|
||||
---
|
||||
name: commit
|
||||
description: Updates changelog and proposes a concise verbal git commit message
|
||||
metadata:
|
||||
version: v2
|
||||
---
|
||||
|
||||
1. Run the changelog skill: read git log and staged changes, then update CHANGELOG.md accordingly (same as /changelog).
|
||||
@@ -9,4 +11,5 @@ description: Updates changelog and proposes a concise verbal git commit message
|
||||
- Concise, verbal style — e.g. "Add X", "Fix Y", "Refactor Z"
|
||||
- NOT filename-style — never "update_something.py" or "changes to foo"
|
||||
- In English
|
||||
- **No AI authorship** — never append `Co-Authored-By: Claude`, a "Generated with …" line, or any tool signature or emoji footer. The same applies to pull request descriptions.
|
||||
- Do NOT run git commit — only propose the message and wait for user confirmation.
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
---
|
||||
name: documentation
|
||||
description: Updates documentation in project
|
||||
metadata:
|
||||
version: v1
|
||||
---
|
||||
Create or update documentation of project in docs/ folder. Documentation should contain description of each part of program and documentation of each function. Separate documents for each module. Write in markdown format.
|
||||
@@ -1,6 +1,8 @@
|
||||
---
|
||||
name: context
|
||||
name: documentation_context
|
||||
description: Compress docs/ into CONTEXT.md at project root — minimum tokens, lossless
|
||||
metadata:
|
||||
version: v2
|
||||
---
|
||||
|
||||
Read every `.md` file in `docs/`. Generate `CONTEXT.md` at the project root.
|
||||
@@ -1,6 +1,6 @@
|
||||
# Godot Development Guidelines
|
||||
|
||||
**Document Version:** v1
|
||||
**Document Version:** v2
|
||||
|
||||
> **Note on Versioning:**
|
||||
> - This document version is independent — reused across Godot projects
|
||||
@@ -90,7 +90,7 @@ Use a dedicated `Log` autoload that wraps `print`/`push_warning`/`push_error` wi
|
||||
|
||||
The file sink retains **max 10 log files**. Each run creates a new file via the timestamp in the filename.
|
||||
|
||||
The `DEBUG` sink is only active when `Constants.DEBUG` is `true` (controlled by an `ENV_DEBUG` value read at startup, e.g. from a `user://settings.cfg` or an export feature tag).
|
||||
The `DEBUG` sink is only active when `Constants.DEFAULT_DEBUG` is `true` (controlled by an `ENV_DEBUG` value read at startup, e.g. from a `user://settings.cfg` or an export feature tag).
|
||||
|
||||
Additional sinks (e.g. an in-game debug overlay / console panel) may be added per project.
|
||||
|
||||
@@ -112,7 +112,7 @@ Additional sinks (e.g. an in-game debug overlay / console panel) may be added pe
|
||||
## 7. Settings and Secrets
|
||||
|
||||
- Store user/runtime config in `user://settings.cfg` via `ConfigFile`
|
||||
- Toggle debug behaviour with an `ENV_DEBUG`-style flag read at startup into `Constants.DEBUG`
|
||||
- Toggle debug behaviour with an `ENV_DEBUG`-style flag read at startup into `Constants.DEFAULT_DEBUG`
|
||||
- Never commit any secrets; keep them out of `project.godot` and committed `.tres`/`.cfg` files
|
||||
|
||||
---
|
||||
@@ -191,7 +191,7 @@ When the game is distributed as a standalone build:
|
||||
godot --headless --export-release "Windows Desktop" build/Game.exe
|
||||
```
|
||||
- Compiled builds are stored in `build/` (or `dist/`). Decide per project whether builds are committed — for small internal distribution the repository may serve as the channel; otherwise keep `build/` in `.gitignore`
|
||||
- Strip debug-only nodes and disable `Constants.DEBUG` in release presets
|
||||
- Strip debug-only nodes and disable `Constants.DEFAULT_DEBUG` in release presets
|
||||
|
||||
> This section applies only to projects that produce shippable builds.
|
||||
|
||||
|
||||
@@ -16,5 +16,5 @@ Each version entry uses these sections (include only those that apply):
|
||||
|
||||
- Follow semantic versioning: `MAJOR.MINOR.PATCH`
|
||||
- Newest version goes at the top
|
||||
- Always update this file before bumping the version in `pyproject.toml`
|
||||
- Always update this file before bumping the version in the project manifest (`pyproject.toml`, `Cargo.toml`, `project.godot`)
|
||||
- Document changes as they are made, not all at once at release time
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Python Development Guidelines
|
||||
|
||||
**Document Version:** v8
|
||||
**Document Version:** v9
|
||||
|
||||
> **Note on Versioning:**
|
||||
> - This document version is independent — reused across projects
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Python Library Development Guidelines
|
||||
|
||||
**Document Version:** v1
|
||||
**Document Version:** v2
|
||||
|
||||
> **Note on Versioning:**
|
||||
> - This document version is independent — reused across projects
|
||||
@@ -127,7 +127,6 @@ Define specific exception types in `src/<package>/exceptions.py`. Use a fail-fas
|
||||
- **pytest** only — no `unittest`, no `TestCase` classes, no `self.assert*`
|
||||
- Arrange-Act-Assert pattern
|
||||
- Test naming: `test_<action>_<context>`
|
||||
- Do not commit `poetry.lock` — this is a library; consumers pin their own dependencies
|
||||
|
||||
---
|
||||
|
||||
|
||||
+14
-5
@@ -8,12 +8,15 @@ Create a `template/` folder in project root with reusable files for new Python p
|
||||
template/
|
||||
├── .env # Environment variables (sample)
|
||||
├── .gitignore # Git ignore rules
|
||||
├── AGENTS.md # AI assistant rules
|
||||
├── CHANGELOG.md # Changelog template
|
||||
├── DESIGN_DOCUMENT.md # Development guidelines
|
||||
├── PROJECT.md # Project documentation template
|
||||
├── main.py # Entry point with loguru
|
||||
├── README.md # Project overview, tool descriptions, build instructions
|
||||
├── <tool_name>.py # Entry point — named by purpose or tool name
|
||||
├── <tool_name>.spec # PyInstaller spec (only for projects shipping an .exe)
|
||||
├── prebuild.py # Pre-build script: venv check, version print, console= rewrite
|
||||
├── pyproject.toml # Poetry config (ruff, mypy, pytest)
|
||||
├── docs/
|
||||
│ └── .gitkeep # Detailed documentation lives here, never in the root
|
||||
├── src/
|
||||
│ ├── __init__.py
|
||||
│ ├── _version.py # Version fallback for PyInstaller
|
||||
@@ -23,12 +26,16 @@ template/
|
||||
└── test_constants.py # Basic test
|
||||
```
|
||||
|
||||
`AGENTS.md` and `DESIGN_DOCUMENT.md` are **not** part of the template — they are copied
|
||||
into the project root from the documentation repository and are never committed.
|
||||
|
||||
## Key Features
|
||||
|
||||
- **Version extraction** from `pyproject.toml` with `_version.py` fallback for PyInstaller builds
|
||||
- **DEBUG mode** via `ENV_DEBUG=true` in `.env` (adds "DEV" suffix to version: v1.2.3DEV)
|
||||
- **loguru** for logging (never print)
|
||||
- **Poetry** for dependency management
|
||||
- **Build configuration** via `ENV_BUILD_CONSOLE` and `ENV_BUILD_SPEC` in `.env`, applied by `prebuild.py`
|
||||
- **loguru** for logging (never print for debugging)
|
||||
- **Poetry** for dependency management, `poetry.lock` committed
|
||||
- **pytest** for testing (no unittest)
|
||||
- **ruff + mypy** for linting and type checking (120-character lines)
|
||||
|
||||
@@ -38,3 +45,5 @@ template/
|
||||
- Generic/reusable format
|
||||
- Keep files simple and minimal
|
||||
- `.gitignore` is the shared core from `Project template/.gitignore` with `Python/.gitignore` appended
|
||||
- Entry point is named by purpose or tool name — a project may have several
|
||||
- `prebuild.py` and the `.spec` file are only needed for projects distributed as a standalone `.exe`
|
||||
|
||||
+4
-2
@@ -4,10 +4,12 @@ from pathlib import Path
|
||||
|
||||
from dotenv import load_dotenv
|
||||
|
||||
from src.constants import VERSION
|
||||
|
||||
# .env must be loaded before src.constants is imported — constants.py reads ENV_DEBUG
|
||||
# at import time to build VERSION.
|
||||
load_dotenv()
|
||||
|
||||
from src.constants import VERSION # noqa: E402
|
||||
|
||||
print("=" * 50)
|
||||
print("PREBUILD CONFIGURATION")
|
||||
print("=" * 50)
|
||||
|
||||
@@ -14,6 +14,11 @@ Dokumentace/
|
||||
│ ├── CLAUDE.md # Claude Code session instructions
|
||||
│ ├── AGENTS.md # Language-agnostic rules for all AI assistants
|
||||
│ └── skills/ # Custom Claude Code skills
|
||||
│ ├── changelog/ # /changelog — update CHANGELOG.md
|
||||
│ ├── check/ # /check — run tests, investigate failures
|
||||
│ ├── commit/ # /commit — changelog + commit message proposal
|
||||
│ ├── documentation/ # /documentation — write docs/
|
||||
│ └── documentation_context/ # /documentation_context — compress docs/ into CONTEXT.md
|
||||
│
|
||||
├── Python/ # Python development guidelines
|
||||
│ ├── DESIGN_DOCUMENT.md # Guidelines for Python applications
|
||||
@@ -38,9 +43,11 @@ Dokumentace/
|
||||
│ ├── PROJECT.md # Project documentation template
|
||||
│ └── .gitignore # Shared, language-agnostic ignore rules
|
||||
│
|
||||
└── Zscaler/ # Corporate network setup
|
||||
├── ZSCALER_CERTIFICATE.md # Cert setup for Node, Python, git, cargo
|
||||
└── ZscalerRootCertificate-2048-SHA256.crt
|
||||
├── Zscaler/ # Corporate network setup
|
||||
│ ├── ZSCALER_CERTIFICATE.md # Cert setup for Node, Python, git, cargo
|
||||
│ └── ZscalerRootCertificate-2048-SHA256.crt
|
||||
│
|
||||
└── CHANGELOG.md # History of this repository
|
||||
```
|
||||
|
||||
## AI Coding Workflow
|
||||
@@ -62,11 +69,38 @@ Where the two disagree, **the design document wins**.
|
||||
|
||||
### Starting a new project
|
||||
|
||||
1. Copy `Project template/PROJECT.md` and `Project template/CHANGELOG.md` into the project root — both are committed.
|
||||
1. Copy `Project template/PROJECT.md` and `Project template/CHANGELOG.md` into the project root and write a `README.md` — all three are committed.
|
||||
2. Build `.gitignore` from `Project template/.gitignore` plus the `.gitignore` of the matching language folder.
|
||||
3. Copy `Claude/AGENTS.md` and the matching `DESIGN_DOCUMENT*.md` into the project root — these are **not** committed, they come from here.
|
||||
4. For Python, follow `Python/TEMPLATE.md` to generate the project skeleton.
|
||||
|
||||
### Skills
|
||||
|
||||
The skills in `Claude/skills/` are the source of truth; the copies Claude Code actually runs live in
|
||||
`~/.claude/skills/`. Install or refresh them by copying the whole folder across.
|
||||
|
||||
Two rules keep the two sides from drifting apart:
|
||||
|
||||
- **The folder name is the command.** For personal skills the frontmatter `name` is only a display
|
||||
label — `/documentation_context` comes from the directory, not from `name:`. Keep the two identical
|
||||
so renaming a folder can never silently change the command.
|
||||
- **Every skill carries a version** in `metadata.version`, incremented on every content change, the
|
||||
same way design documents carry `Document Version`:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: commit
|
||||
description: Updates changelog and proposes a concise verbal git commit message
|
||||
metadata:
|
||||
version: v2
|
||||
---
|
||||
```
|
||||
|
||||
There is no top-level `version:` field in the skill format. `metadata` is a free-form map that
|
||||
Claude Code ignores, and it is one of the six fields the [Agent Skills](https://agentskills.io)
|
||||
spec allows — so it also survives an upload to claude.ai or the Skills API. Any other invented
|
||||
key fails packaging with `Unexpected key(s) in SKILL.md frontmatter`.
|
||||
|
||||
## Key Conventions
|
||||
|
||||
- **Python tooling:** Poetry · Ruff · mypy · pytest · loguru
|
||||
@@ -74,7 +108,7 @@ Where the two disagree, **the design document wins**.
|
||||
- **Godot tooling:** gdformat · gdlint · GUT
|
||||
- **No `print()` for debugging** — the language's logging library, everywhere
|
||||
- **Static typing required** on every parameter and return value
|
||||
- **Line length:** 120 characters (Python), 100 soft limit (GDScript)
|
||||
- **Line length:** 120 characters (Python), 100 characters (Rust, rustfmt default), 100 soft limit (GDScript)
|
||||
- **Tests:** the framework named in the design document — pytest (Python, never `unittest`), built-in `#[test]` (Rust), GUT (Godot)
|
||||
- **Tasks:** single-line `TODO` / `FIXME` / `BUG` / `HACK` / `NOTE` comments in code — no checkboxes in documentation
|
||||
- **Versioning:** semantic, always ask before bumping, `CHANGELOG.md` updated first
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Rust Application Development Guidelines
|
||||
|
||||
**Document Version:** v1
|
||||
**Document Version:** v2
|
||||
|
||||
> **Note on Versioning:**
|
||||
> - This document version is independent — reused across projects
|
||||
@@ -25,6 +25,7 @@ The root directory contains only the core documents: `README.md`, `AGENTS.md`, `
|
||||
## 1. Code Style
|
||||
|
||||
- **Rust edition:** 2024 (requires Rust 1.85 or newer)
|
||||
- **100-character lines** (rustfmt default `max_width`)
|
||||
- Format with **rustfmt** — run `cargo fmt` before every commit
|
||||
- Lint with **clippy** — run `cargo clippy -- -D warnings` before every commit
|
||||
- **snake_case** functions/variables/modules, **PascalCase** types/traits, **SCREAMING_SNAKE_CASE** constants
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Rust Library Development Guidelines
|
||||
|
||||
**Document Version:** v1
|
||||
**Document Version:** v2
|
||||
|
||||
> **Note on Versioning:**
|
||||
> - This document version is independent — reused across projects
|
||||
@@ -28,6 +28,7 @@ The root directory contains only the core documents: `README.md`, `AGENTS.md`, `
|
||||
|
||||
- **Rust edition:** 2024 (requires Rust 1.85 or newer)
|
||||
- Declare the minimum toolchain in `Cargo.toml` (`rust-version = "1.85"`) so consumers get a clear error instead of a compile failure
|
||||
- **100-character lines** (rustfmt default `max_width`)
|
||||
- Format with **rustfmt** — run `cargo fmt` before every commit
|
||||
- Lint with **clippy** — run `cargo clippy -- -D warnings` before every commit
|
||||
- **snake_case** functions/variables/modules, **PascalCase** types/traits, **SCREAMING_SNAKE_CASE** constants
|
||||
@@ -169,8 +170,6 @@ mod tests {
|
||||
}
|
||||
```
|
||||
|
||||
`Cargo.lock` is **not committed** for libraries — add it to `.gitignore`. Consumers pin their own dependency graph.
|
||||
|
||||
---
|
||||
|
||||
## 9. Documentation
|
||||
|
||||
Reference in New Issue
Block a user