mirror of https://github.com/opentibiabr/canary synced 2026-08-16 06:26:09 -04:00

docs(agents): route build validation workflow (#4089 )

Keep Canary's active repository instructions concise while moving the complete local build-validation workflow into dedicated documentation.

Main changes:
- Reduce detailed build procedures in AGENTS.md and route them through docs/building/local-validation.md.
- Keep repository-wide build invariants in the always-loaded instruction layer.
- Require maintained build entry points to stay synchronized when C++ source or header files are added, removed, or renamed.
- Keep the relevant CMakeLists.txt, vcproj/canary.vcxproj, and test CMakeLists.txt registration requirements explicit.
- Clarify that local builds remain opt-in unless explicitly requested or authorized at the completion point of a larger task.

Local validation documentation:
- Add docs/building/local-validation.md.
- Document the supported Windows CMake and Visual Studio validation workflow.
- Document Visual Studio Developer Command Prompt and Developer PowerShell environment requirements.
- Document project-managed VCPKG_ROOT verification before configuring or building.
- Document the preferred windows-release preset workflow.
- Document how to inspect and reuse existing CMake preset caches.
- Document targeted recovery from incompatible or corrupted CMake/Ninja cache state.
- Avoid broad cache deletion or creating ad-hoc build directories as a recovery path.
- Document maintained Visual Studio solution and generated build entry-point checks.

MSVC Ninja dependency tracking:
- Document that Ninja requires matching raw cl.exe /showIncludes output to populate .ninja_deps correctly.
- Require configure and build steps to use a consistent environment and code page.
- Keep compiler launchers disabled for MSVC Ninja validation.
- Document diagnosis using rules.ninja, msvc_deps_prefix, raw /showIncludes output, and ninja -t deps.
- Clarify that ninja -t recompact cannot recreate missing dependency records.
- Document recovery for malformed or empty .ninja_deps without broad-cleaning build state.

Instruction budget:
- Keep detailed workflows out of the always-loaded AGENTS.md when they can be routed to versioned documentation.
- Preserve headroom for global and narrower scoped instructions.
- Prefer removing duplicated guidance before increasing instruction byte limits.

Validation:
- Audited the effective global and repository instruction chain at 18,449 bytes.
- Verified it remains below the 24 KiB maintenance target and default Codex instruction cap.
- Verified the routed local-validation documentation path exists.
- Reviewed the complete committed diff.
- Ran Git whitespace validation successfully.
- No build was run because this is a documentation-only change and no build was requested.

This keeps the active instruction layer smaller while preserving the full Canary build-validation, cache-recovery, and MSVC Ninja dependency-tracking workflow in a dedicated maintained document.

2026-08-15 00:56:10 -03:00

3.4 KiB

Raw Permalink Blame History

Canary-specific guidance

The global Git, commit, PR, C++ header, exception, and documentation policies apply. This file only records Canary-specific gates.

Recurring Defect Prevention

For a reusable defect, inspect analogous paths by behavior and ownership, fix confirmed siblings atomically, and keep the audit proportional; do not turn a one-off into a speculative refactor.
Decide whether tooling makes recurrence impossible. If not, add a narrow rule to the nearest AGENTS.md that states the unsafe pattern, required alternative, and validation rather than incident history.
Prefer enforceable safeguards—types, helpers, static checks, architecture docs, or focused tests—especially for lifetime, arithmetic, identity, ownership, bounds, and cancellation escapes.

Deferred Callback Lifetime Safety

Assume scheduled, deferred, timer, and worker callbacks can outlive their source object or state.
Never capture raw this, references, iterators, or mutable-container pointers across that boundary. Use immutable values plus std::weak_ptr or re-resolvable identity validated with the original identity, generation, epoch, or session token.
Removal, replacement, reload, or reinterpretation must cancel pending work or advance a checked generation. Callback-owning types are non-movable unless moving cancels or safely rebinds every event.
Use bounded arithmetic for intervals; stale work must become a no-op before gameplay, Lua, combat, movement, persistence, or client output. Cover destroyed/replaced owners, reused IDs, shutdown, and ownership transfer where practical.

Canary build discipline

Before an authorized local build, read docs/building/local-validation.md; its maintained entry-point, environment, preset, cache, and MSVC Ninja workflow is mandatory.
C++ source/header additions, removals, and renames must update every maintained entry: the relevant CMake list, server vcproj/canary.vcxproj, and test CMake list when applicable.

MSVC Ninja dependency tracking

Before configuring, repairing, or auditing an MSVC Ninja build, read docs/building/local-validation.md#msvc-ninja-dependency-tracking. Its code-page, launcher, dependency-log, and concurrency rules remain mandatory.

Precompiled Header Policy

src/pch.hpp owns broad shared standard includes; do not duplicate an unguarded PCH include.
Headers must declare their public dependencies. When a source needs a PCH-provided include without PCH, guard it with #ifndef USE_PRECOMPILED_HEADERS; add broad includes to the PCH with the same local fallback.

Lua Shared Userdata Gate

Before changing std::shared_ptr Lua userdata, read docs/systems/lua-shared-userdata.md and use its typed trait, registration, and push helpers.
Never combine shared pushUserdata with a manual metatable, use a weak metatable for shared userdata, or wrap a borrowed object without a no-op deleter. Run the document's two rg checks and investigate every match.

Docker Quickstart Policy

For quickstart changes, read docs/docker/quickstart-for-beginners.md and docker/DOCKER.md; keep CI/build, development, and user quickstart responsibilities separate.
The default client path is login-server at http://localhost:8088/login, never MyAAC login.php. MyAAC remains website/admin-only, uses slawkens/myaac develop, and keeps http://localhost:8080; public config stays CANARY_*, and the quickstart uses the published Canary runtime image.

3.4 KiB Raw Permalink Blame History