Add per-script and plugin versioning with changelog rules

2026-10-12 15:59:21 -04:00
parent b508b6739b
commit e95ebe3117
4 changed files with 212 additions and 0 deletions
@@ -0,0 +1,58 @@
+# 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.