From 080742d35d9af087c116a4432e4631cdc1077a76 Mon Sep 17 00:00:00 2001 From: Andreas Stefl Date: Sun, 14 Jun 2026 22:33:42 +0200 Subject: [PATCH 1/3] AGENTS.md: record test-running, PR, and code-style conventions - run the full test suite only when necessary (it is slow); prefer targeted --gtest_filter, and run the test binary from the build dir so its output does not pollute the repo - put the "Generated with Claude Code" line at the top of PR bodies - prefer fixed-width types over unsigned char / long & co - document with /// doc comments (and trailing ///< for same-line notes) Co-Authored-By: Claude Opus 4.8 --- AGENTS.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index ac48c5e2..0b6d459d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -87,11 +87,17 @@ A configured build dir already exists (`cmake-build-relwithdebinfo`, also `…-d cmake --build cmake-build-relwithdebinfo --target odr # tests (the ODR_TEST option is on in this build dir) cmake --build cmake-build-relwithdebinfo --target odr_test -./cmake-build-relwithdebinfo/test/odr_test --gtest_filter='OldMs.*' +# run from inside the build dir so any test output stays out of the repo tree +(cd cmake-build-relwithdebinfo && ./test/odr_test --gtest_filter='OldMs.*') # CLI (renders a file to a directory of HTML) cmake --build cmake-build-relwithdebinfo --target translate ``` +- **Only run the full suite when really necessary** — it takes a while. Default + to a targeted `--gtest_filter` for the area you touched. +- **Run the test binary from the build directory** (as above) so any files it + writes land there, not in the repo working tree. + Notable CMake options (`CMakeLists.txt`): `ODR_TEST`, `ODR_CLI`, `ODR_WITH_PDF2HTMLEX`, `ODR_WITH_WVWARE`, `ODR_WITH_LIBMAGIC`, `ODR_CLANG_TIDY`. A new `.cpp` must be added to the `ODR_SOURCE_FILES` list in `CMakeLists.txt`. @@ -123,6 +129,14 @@ A new `.cpp` must be added to the `ODR_SOURCE_FILES` list in `CMakeLists.txt`. restate the code or spell out every case; cite the spec instead of paraphrasing it. The detailed design rationale belongs in the per-module `AGENTS.md`, not in source comments. +- **Doc-comment markers**: document functions, classes, structs and enums with + `///` doc comments; use a trailing `///<` for the short note on the same line + (e.g. an enumerator or member). Keep them terse per the rule above. +- **Fixed-width integer types**: prefer `` types (`std::uint8_t`, + `std::uint32_t`, …) over `unsigned char` / `unsigned` / `long` and friends + whenever the width matters (byte buffers, on-disk/wire fields, bit math). +- **Pull requests**: put the `🤖 Generated with [Claude Code](https://claude.com/claude-code)` + line **at the top** of the PR body. ## Adding / extending a document format From 41ae23d4fe6b7605627a3a4ae1937633cf0fdef1 Mon Sep 17 00:00:00 2001 From: Andreas Stefl Date: Sun, 14 Jun 2026 22:37:17 +0200 Subject: [PATCH 2/3] AGENTS.md: prefer the relwithdebinfo build directory Co-Authored-By: Claude Opus 4.8 --- AGENTS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 0b6d459d..39c8a678 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -93,6 +93,8 @@ cmake --build cmake-build-relwithdebinfo --target odr_test cmake --build cmake-build-relwithdebinfo --target translate ``` +- **Use `cmake-build-relwithdebinfo`** as the default build/test directory (not + `cmake-build-debug`). - **Only run the full suite when really necessary** — it takes a while. Default to a targeted `--gtest_filter` for the area you touched. - **Run the test binary from the build directory** (as above) so any files it From 9ab3f5d40f64543e0851d7ff2cee7c5dab4fa1e9 Mon Sep 17 00:00:00 2001 From: Andreas Stefl Date: Sun, 14 Jun 2026 22:39:18 +0200 Subject: [PATCH 3/3] AGENTS.md: prefer the translate CLI for debugging Co-Authored-By: Claude Opus 4.8 --- AGENTS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 39c8a678..53a530a5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -97,6 +97,8 @@ cmake --build cmake-build-relwithdebinfo --target translate `cmake-build-debug`). - **Only run the full suite when really necessary** — it takes a while. Default to a targeted `--gtest_filter` for the area you touched. +- **For debugging, prefer the `translate` CLI** over the test suite — build and + run it on a single file to reproduce/inspect behaviour quickly. - **Run the test binary from the build directory** (as above) so any files it writes land there, not in the repo working tree.