Contribution workflow

Follow Akron’s expected change, testing, documentation, verification, and review flow for contributor work.

Define the user-visible behavior first. Then classify, implement, and verify it.

Normal flow

1. Define the behavior and user goal.
2. Decide the policy unit and classification.
3. Update source code and tests.
4. Update CHANGELOG.md when the change is notable and user-facing.
5. Update public docs if behavior, settings, policy, or file contracts changed.
6. Update contributor docs if implementation boundaries, policy rules, or verification expectations changed.
7. Run formatting checks, focused tests, and build.
8. Add live verification evidence when required.
9. Disclose AI assistance when any AI tool materially helped produce the change.

Files by concern

Concern	Primary files
Feature kind and policy metadata	Source/Core/AkronTypes.cs, Source/Core/AkronFeatureRegistry.cs
Overlay rows, control types, and tooltip controls	Source/Overlay/AkronOverlay.cs plus focused Source/Overlay/akron-overlay-*.cs partials
Persisted settings and setup state	Source/Module/AkronModuleSettings.cs, Source/Module/akron-module-settings-*.cs, Source/Setups/akron-setup-*.cs
Runtime behavior	Source/Module/AkronModule.cs, Source/Actions/akron-actions.cs, Source/Runtime/akron-runtime-options.cs, feature-specific runtime partials
HUD rendering	Source/Hud/AkronHudRenderer.cs, Source/Hud/akron-hud-*.cs
Save/load internals	Source/SaveLoad/AkronSaveLoad.cs, Source/SaveLoad/akron-save-load-*.cs
Internal recording	Source/Recorder/akron-internal-recorder*.cs, Source/Recorder/akron-internal-audio-recorder.cs
.akr archive contract	Source/Packs/akron-archive.cs
Setup archives and file picker	Source/Setups/akron-setup-packs.cs, Source/Setups/akron-setup-file-picker.cs
Theme archives	Source/Overlay/akron-overlay-themes.cs
HUD-label archives	Source/Hud/akron-custom-hud-label-catalog.cs
Control-display archives	Source/Input/akron-input-board.cs
Debug and automation commands	Source/Commands/akron-commands.cs, Source/Commands/akron-*-commands.cs
Verification	tests/feature-registry-tests.cs, tests/module-settings-tests.cs, feature-specific tests

Documentation expectations

Update docs when:

• A visible feature changes behavior.
• A policy classification changes.
• An active setup default, .akr pack scope, or .akr section changes.
• A file location, command, or archive contract changes.
• A troubleshooting path changes.
• A notable user-facing change needs a CHANGELOG.md entry.

Public docs should explain supported current behavior. Historical research notes, current task maps, and one-off audit checklists should not be published as docs pages unless they describe a current contract.

Review evidence

Provide the smallest evidence that proves the change:

• Test output for unit-level changes.
• Formatting output from dotnet format Akron.sln --include <changed-csharp-files>.
• Build output for source changes.
• Screenshot or capture evidence for visual behavior.
• Live verification notes for input, timing, camera, hitbox, transition, overlay, or map-dependent behavior.
• Screenshot or video proof for new options or features when the behavior is visible, input-driven, timing-sensitive, rendering-sensitive, capture-related, or gameplay-facing.
• After evidence for fixes when the corrected behavior is visible or runtime-observable. Before evidence is preferred when it is practical to capture or reproduce.

Use screenshots for static UI, overlay, path, policy, or layout behavior. Use video for animation, input timing, recording, screen transitions, camera movement, hitboxes, or gameplay state changes.

Pull request checklist

• Keep the diff scoped to one goal.
• Run dotnet format Akron.sln --include <changed-csharp-files> for changed C# project files.
• Include the tests or checks that were run.
• Include screenshot or video proof for new visible, input-driven, timing-sensitive, rendering-sensitive, capture-related, or gameplay-facing options and features.
• Include after evidence for fixes when the corrected behavior is visible or runtime-observable.
• Include before evidence for fixes when practical, especially for visual, overlay, capture, or gameplay regressions.
• Include live verification notes when unit tests cannot prove the behavior.
• Update docs for user-facing behavior, policy, file locations, debug commands, or .akr contracts.
• Update CHANGELOG.md for notable user-facing changes.
• Avoid committing secrets, local tokens, personal config files, local captures, or machine-specific paths.
• Include the AI assistance disclosure when applicable.

Contribution license

Read the canonical contribution terms in CONTRIBUTING.md. The repository copy owns this policy so the legal text does not drift between surfaces.

AI-assisted contributions

AI-assisted contributions are allowed. They must meet the same code, docs, policy, and verification bar as hand-written changes.

The contributor is responsible for the full contribution, including AI-assisted code, tests, docs, screenshots, created assets, and pull request text.

When AI assistance materially helped produce a pull request, include these fields in the pull request body:

Field	What to provide
agent_name	The AI tool, coding assistant, or agent used.
agent_version	The exact version of the tool, extension, CLI, or agent when available.
model_used	The exact provider model identifier. If the tool provides no way to determine it, write model_not_exposed and explain why. Do not guess.
human_testing	Tests, checks, live Celeste verification, screenshots, or manual review performed by a human.
contribution_summary	One sentence describing what changed.

Disclosure fields must be factual. Do not claim human review, testing, verification, or approval unless it actually happened.

human_testing must describe real work that happened. Examples:

• Ran dotnet test tests/akron-tests.csproj --nologo --filter FeatureRegistryTests.
• Built Source/Akron.csproj and manually checked the overlay in 7A with the overlay active.
• Reviewed the .akr pack in Saves/AkronSetups and imported it through the Interface tab.

No human testing performed is not acceptable for a pull request that is ready to merge.