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"
 }