Build Scripts, Tooling, and Review

Copyright notices

Every project-authored file must carry a Nelaric copyright notice when its format permits one. In a text file that supports comments, the notice must be the first logical line, before a heading, code, configuration entry, or other prose. A UTF-8 BOM does not count as a line. Use Copyright (c) <year> Nelaric, where <year> is the file's first publication year; do not update it merely because the file changes.

Use the format's native comment syntax:

File format	First line
C++, C#, and JavaScript source	// Copyright (c) 2026 Nelaric
Markdown and HTML	<!-- Copyright (c) 2026 Nelaric -->
Python, shell, YAML, and hash-comment configuration	# Copyright (c) 2026 Nelaric

If an executable script needs a shebang, keep #!... on line one and put the copyright notice immediately on line two. If a format requires another first-line directive, put the notice at the first legal comment position. Do not add comments to strict JSON or another format that forbids them. Do not prepend a comment to LICENSE or alter its license text; its existing copyright line is authoritative. Binary assets, generated files, and unmodified third-party files retain their own applicable attribution and are exempt from an in-file Nelaric header. Record ownership for project-authored files that cannot carry a notice in the repository license or a nearby notice file rather than breaking the file format.

Apply this rule to every new project-authored file and to existing project-authored files when modifying them. Reviewers must check the header or documented format exception. Keep existing third-party notices intact; do not claim copyright over code or assets Nelaric does not own.

Unreal build scripts

Apply CSharpier to .Build.cs and .Target.cs. It is as mandatory as clang-format for C++.
Keep module dependencies minimal and classify them as public or private according to the headers that need them. Do not put vendor SDK dependencies in GameplayRuntime.
Target UE 5.6 and later. Engine compilation CI should cover both the minimum supported release and the latest supported release. CircleCI builds the Linux Game, Editor, and Server targets with UE 5.6.1 before merge; the latest supported release remains a coverage gap. See Docs/DevelopmentWorkflow.md.

Automation tests

Each independent framework capability must have automated tests that exercise its observable behavior. Add or update those tests with the capability or a behavior change, including meaningful failure and boundary cases where they affect its contract. Name framework-authored Unreal automation tests under the Nelaric.* hierarchy so CI can select them. Group related scenarios into a small number of focused tests per capability. Do not create a separate test for every method, branch, or minor variation, or accumulate large numbers of overlapping tests in one module. Test count and line coverage are not targets; reviewers judge whether the behavior and important risks are covered.

Local checks

Use the versions fixed by .github/workflows/quality.yml and .config/dotnet-tools.json:

python Scripts/check_text.py checks text encoding and line endings.
python Scripts/check_format.py checks C++ and UE build-script formatting. Install the pinned clang-format and restore the local .NET tool manifest first.
python Scripts/check_public_docs.py checks every public header for an @file comment and methods in each class's first public: section for Doxygen comments. It rejects another access specifier between the first and second public: sections. The second section is not checked for method comments.
python Scripts/check_doxygen_style.py checks the 25- and 75-character limits, single- and multi-line forms, a tag at the start of every multi-line paragraph, and consistent enum comment style and alignment.
python Scripts/run_doxygen.py builds the API site and fails on Doxygen warnings. Install the pinned Doxygen release first.

Before requesting review, run the local checks relevant to your change. Pull requests must pass the format, API documentation, PR naming, and Linux project build status before merge. CircleCI builds the submitted project commit, including for branches in this repository. Fork PRs that change CI workflows, automation, Unreal build scripts, or plugin descriptors need a maintainer to handle those changes in a source-repository branch. No clang-tidy or numeric code coverage threshold is required now.

Commit and branch names

Use only these prefixes for new commits and working branches:

Prefix	Purpose
feat	Add a capability.
fix	Correct a defect.
docs	Change documentation only.
style	Change formatting without changing behavior.
refactor	Restructure code without changing behavior.
perf	Improve performance.
test	Add or change tests.
build	Change build configuration or dependencies.
ci	Change automation and CI workflows.
chore	Perform repository maintenance not covered above.
revert	Revert an earlier change.

Commit subjects must use <prefix>: <short English summary> or <prefix>(<scope>): <short English summary>. Use a lowercase scope when present and start the summary with a verb. Squash-merge commit titles must follow the same rule. Examples: feat(session): add reservation support and docs: clarify provider boundaries.

PR titles must follow the same format as commit subjects. CI checks the PR title, source branch, and every commit subject in the PR. It checks the allowed prefix, structure, and an English summary beginning with a lowercase letter; reviewers confirm that the first word is a verb and that the summary describes the change.

Working branches must use <prefix>/<lowercase-kebab-case-description>, for example fix/admission-timeout. The prefix must come from the table above; main is the reserved default-branch exception. Do not introduce another prefix without first updating this standard.

Text-file exceptions

Human-written Markdown and LICENSE, C++ source and headers, and UE C# build scripts use UTF-8 BOM and CRLF. .gitattributes, .editorconfig, .clang-format, .csharpierrc, .gitignore, .json, .yml, .yaml, Doxyfile, and executable .py scripts use UTF-8 without BOM and LF for tool compatibility. The checker enforces these categories.

Review

Review correctness, copyright notices, module boundaries, the accuracy of public API documentation, cancellation and failure behavior, ownership, performance, security, and the automated tests for each independent framework capability. CI checks mechanical Doxygen style; reviewers judge whether comments describe the actual contract and whether tests cover meaningful behavior without unnecessary duplication. A PR seeking an exception to a project guideline must name the rule, reason, affected code, and alternatives. A maintainer must approve the exception; it cannot override an Epic requirement or resolve a conflict between the standards. Report such conflicts in an issue. Current CI success is sufficient as an automated gate, but does not replace review of the required tests.

Reviewers must verify that every project-authored UCLASS explicitly uses MinimalAPI, has no class-level *_API macro, and exports only the individual methods needed across modules, as required by UCLASS exports.