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.
@@ -0,0 +1,100 @@
+# Changelog
+
+Changes are listed newest first, with an independent version for every individual
+T5/T6 script and each native plugin. Current versions are recorded in
+[versions.json](versions.json); see the [version policy](README.md#versioning).
+
+## 2026-10-12
+
+### Initial versioning baseline
+
+Established independent version `1.0.0` entries for each of the 14 scripts and
+both plugins from source commit
+`b508b6739b185d5048e8a8f96ccb16e429f1d37a`. This records the existing source state;
+earlier changes remain in Git history without retroactively assigned versions.
+The baseline introduces `versions.json`, this changelog, the README links and
+version policy, and the maintenance rules in `AGENTS.md`. It changes no game
+script or plugin behavior and requires no deployment by itself.
+
+The component entries below summarize the existing functionality and deployment
+requirements for servers adopting this baseline. Version assignment does not
+indicate that a Windows build, live-game validation, or deployment was performed.
+
+### T5 script baselines
+
+Each row is a separately versioned script under `t5/scripts/`.
+
+| Script | Version | Existing functionality |
+| --- | --- | --- |
+| `tws_t5_afk.gsc` | `1.0.0` | AFK toggle, protection, and indicator |
+| `tws_t5_common.gsc` | `1.0.0` | Shared configuration, helpers, commands, and player dispatchers |
+| `tws_t5_hud.gsc` | `1.0.0` | Timers, zombie count, and health display |
+| `tws_t5_join.gsc` | `1.0.0` | Immediate join for newcomers |
+| `tws_t5_leaderboard.gsc` | `1.0.0` | Map record announcements and `.leaders` command |
+| `tws_t5_lock.gsc` | `1.0.0` | Lobby lock at the configured round milestone |
+| `tws_t5_telemetry.gsc` | `1.0.0` | Game reports, durable boundary retries, balance and cumulative score |
+
+- Compatibility: these initial script versions use `tws_t5_common.gsc` `1.0.0`;
+  lobby lock also needs `tws_t5_hud.gsc` `1.0.0`. Telemetry and leaderboard use
+  TWS T5 plugin `1.0.0`. Telemetry additionally requires
+  Electric Cherry's match/sequence deduplication and `score_total` support;
+  follow the [receiver and plugin rollout order](README.md#telemetry-delivery-and-rollout-t5-and-t6).
+  Disabling telemetry by dvar does not remove its native linking requirements.
+- Deployment: follow the [T5 installation/upgrade instructions](t5/scripts/README.md#install--upgrade),
+  copy the desired scripts and their required dependencies to
+  `storage/t5/scripts/sp/`, and restart the map.
+  Installing or updating the required plugin needs a full server-process restart.
+
+### T6 script baselines
+
+Each row is a separately versioned script under `t6/scripts/`, adapted to T6 APIs
+and map variants.
+
+| Script | Version | Existing functionality |
+| --- | --- | --- |
+| `tws_t6_afk.gsc` | `1.0.0` | AFK toggle, protection, and indicator |
+| `tws_t6_common.gsc` | `1.0.0` | Shared configuration, helpers, commands, and player dispatchers |
+| `tws_t6_hud.gsc` | `1.0.0` | Timers, zombie count, and health display |
+| `tws_t6_join.gsc` | `1.0.0` | Immediate join for newcomers |
+| `tws_t6_leaderboard.gsc` | `1.0.0` | Map record announcements and `.leaders` command |
+| `tws_t6_lock.gsc` | `1.0.0` | Lobby lock at the configured round milestone |
+| `tws_t6_telemetry.gsc` | `1.0.0` | Game reports, durable boundary retries, balance and cumulative score |
+
+- Compatibility: these initial script versions use `tws_t6_common.gsc` `1.0.0`;
+  lobby lock also needs `tws_t6_hud.gsc` `1.0.0`. Telemetry and leaderboard use
+  TWS T6 plugin `1.0.0`. Telemetry additionally requires
+  Electric Cherry's match/sequence deduplication and `score_total` support;
+  follow the [receiver and plugin rollout order](README.md#telemetry-delivery-and-rollout-t5-and-t6).
+  Disabling telemetry by dvar does not remove its native linking requirements.
+- Deployment: follow the [T6 installation instructions](t6/scripts/README.md#install),
+  copy the desired scripts and their required dependencies to
+  `storage/t6/scripts/zm/`, and restart the map.
+  Installing or updating the required plugin needs a full server-process restart.
+
+### T5 plugin — 1.0.0
+
+- Baseline: the TWS-maintained plugin, including configurable HTTP deadlines,
+  status/timing diagnostics, and durable telemetry storage and response helpers.
+- Source covered: `t5/plugins/tws-t5-gsc-utils/` and the existing shared plugin
+  build/dependency tooling under `tools/`.
+- Compatibility: provides the native functions used by `tws_t5_telemetry.gsc`
+  `1.0.0` and `tws_t5_leaderboard.gsc` `1.0.0`.
+  Upstream source and dependency pins remain in the plugin's `upstream.json`.
+  Upstream binary downloads do not include these TWS changes.
+- Deployment: [build the x86 DLL on Windows](README.md#building-plugins), install
+  `tws-t5-gsc-utils.dll` in `Plutonium/plugins/`, remove the old upstream DLL if
+  present, and restart the full server process before loading dependent scripts.
+
+### T6 plugin — 1.0.0
+
+- Baseline: the matching TWS T6 plugin with configurable HTTP deadlines,
+  status/timing diagnostics, and durable telemetry storage and response helpers.
+- Source covered: `t6/plugins/tws-t6-gsc-utils/` and the existing shared plugin
+  build/dependency tooling under `tools/`.
+- Compatibility: provides the native functions used by `tws_t6_telemetry.gsc`
+  `1.0.0` and `tws_t6_leaderboard.gsc` `1.0.0`.
+  Upstream source and dependency pins remain in the plugin's `upstream.json`.
+  Upstream binary downloads do not include these TWS changes.
+- Deployment: [build the x86 DLL on Windows](README.md#building-plugins), install
+  `tws-t6-gsc-utils.dll` in `Plutonium/plugins/`, remove the old upstream DLL if
+  present, and restart the full server process before loading dependent scripts.
@@ -2,6 +2,8 @@

 Combined working repo for the TWS Plutonium Zombies scripts and native plugins across two games.

+[Changelog](CHANGELOG.md) · [Current component versions](versions.json)
+
 ## Layout

 - [t5/scripts/](t5/scripts/) — T5 GSC modules, [README](t5/scripts/README.md), and [notes](t5/scripts/NOTES.md).
@@ -12,6 +14,40 @@ Combined working repo for the TWS Plutonium Zombies scripts and native plugins a
 The scripts still deploy to the game's existing `storage/t5/scripts/sp/` or
 `storage/t6/scripts/zm/` directories; the new source layout does not change GSC namespaces.

+## Versioning
+
+[versions.json](versions.json) records the current source version of each
+individual script and each native plugin. Every `.gsc` file has its own version,
+keyed by its exact filename. Changing one script bumps only that script's version;
+other scripts increase only when their own source changes.
+
+| Component | Manifest key | Source |
+| --- | --- | --- |
+| Each T5 script | Exact filename, e.g. `tws_t5_afk.gsc` | Corresponding file in `t5/scripts/` |
+| Each T6 script | Exact filename, e.g. `tws_t6_afk.gsc` | Corresponding file in `t6/scripts/` |
+| T5 plugin | `t5-plugin` | `t5/plugins/tws-t5-gsc-utils/` |
+| T6 plugin | `t6-plugin` | `t6/plugins/tws-t6-gsc-utils/` |
+
+Every completed script or plugin change includes a version bump for each
+affected component and an entry in [CHANGELOG.md](CHANGELOG.md). Each entry
+identifies each changed script or plugin and its new version, compatibility
+requirements, and deployment steps. Shared helpers such as `tws_t5_common.gsc`
+have their own versions; document required dependency versions when compatibility
+changes. A shared helper change alone does not bump its unchanged consumers.
+Changes to shared build/dependency tooling also bump the plugins they affect.
+
+Versions use `MAJOR.MINOR.PATCH`: increase the patch for fixes and internal
+changes, the minor for compatible features, and the major for breaking changes
+to commands, configuration, native APIs, or data contracts. Reset lower fields
+when increasing the minor or major. Bump once per logical change; documentation-only
+and test-only changes are exempt. All 14 scripts and both plugins advance independently.
+
+The initial `1.0.0` versions document the existing source baseline. These TWS
+versions are separate from upstream revisions in each plugin's `upstream.json`
+and the existing native loader `plugin_version()` value. Component versions
+identify source changes; consult the changelog for compatible script/plugin
+combinations and receiver requirements. Maintenance rules are in [AGENTS.md](AGENTS.md).
+
 ## Building plugins

 Plugin source is vendored as regular tracked files so local modifications travel
@@ -0,0 +1,18 @@
+{
+  "tws_t5_afk.gsc": "1.0.0",
+  "tws_t5_common.gsc": "1.0.0",
+  "tws_t5_hud.gsc": "1.0.0",
+  "tws_t5_join.gsc": "1.0.0",
+  "tws_t5_leaderboard.gsc": "1.0.0",
+  "tws_t5_lock.gsc": "1.0.0",
+  "tws_t5_telemetry.gsc": "1.0.0",
+  "tws_t6_afk.gsc": "1.0.0",
+  "tws_t6_common.gsc": "1.0.0",
+  "tws_t6_hud.gsc": "1.0.0",
+  "tws_t6_join.gsc": "1.0.0",
+  "tws_t6_leaderboard.gsc": "1.0.0",
+  "tws_t6_lock.gsc": "1.0.0",
+  "tws_t6_telemetry.gsc": "1.0.0",
+  "t5-plugin": "1.0.0",
+  "t6-plugin": "1.0.0"
+}