# Repository instructions

## Versioning and changelog

- Follow the component boundaries and version policy in
  [README.md](README.md#versioning). [versions.json](versions.json) is the
  authoritative source for current TWS component versions.
- Each `.gsc` file has its own version in `versions.json`, keyed by its exact
  filename. Every completed edit to a game script must bump that script's
  version and add a matching entry to [CHANGELOG.md](CHANGELOG.md) in the same
  change. This includes refactors and comment-only edits to script source.
  Bump only scripts whose source changes; an unchanged script does not inherit
  a bump from its game, a shared helper, or its T5/T6 counterpart. Document
  required dependency versions when a shared helper or native API change affects
  compatibility.
- Give each new script its own `1.0.0` entry. For a rename, carry forward and
  bump its version under the new filename, recording both filenames in the
  changelog. For removal, record the next version as the final removal entry in
  the changelog and remove the filename from the active manifest.
- Every completed change to a plugin's source, pinned dependencies, or build
  behavior must bump that plugin's version and add a matching changelog entry.
  Changes to shared build/dependency tooling that affect both plugins require
  both versions to increase.
- Bump each affected script or plugin once per logical change, not once per
  editing operation. Use the highest applicable bump: patch for fixes or
  internal changes, minor for compatible features, major for breaking changes.
  Reset lower version fields when increasing the minor or major version.
- Documentation-only and test-only changes do not require a component version
  bump. A documentation or test edit accompanying a script/plugin change does
  not exempt that component from a bump. Ignored build outputs and dependency
  checkouts do not count as source changes.
- Add entries newest first under the actual change date (`YYYY-MM-DD`), with a
  heading or table row identifying each affected script or plugin and its new
  version. Record what changed,
  affected source files, compatibility requirements, and deployment steps,
  including whether a map restart or full server-process restart is required.
  State explicitly when there is no new dependency requirement or deployment
  action. Preserve previous entries; extend the current entry while completing
  the same logical change.
- Consider the matching T5/T6 implementation for every game-specific change.
  Adapt companion changes to that engine and bump each component actually
  changed. If the companion needs no change, briefly explain why in the
  changelog entry. Version numbers do not need to match across components.
- Keep TWS component versions separate from upstream revision pins and the
  native loader's existing `plugin_version()` value. A TWS version bump alone
  must not rewrite either. Never invent historical releases or describe an
  unperformed build, test, or deployment as completed.

## Verification

- Before finishing, confirm that every affected component has a version bump
  and a changelog entry with the same version (or its initial/removal entry).
  Ensure every existing game script has exactly one filename entry in
  `versions.json`, with no stale entries for removed scripts. Check JSON validity,
  local documentation links, and `git diff --check` after metadata changes.
- Run the checks relevant to the change using the root and component READMEs.
  Report checks performed and any remaining Windows/Plutonium validation.
  Documentation or version-metadata changes alone do not require game builds.