Clean up README and organize documentation

2026-10-06 23:51:41 -04:00
parent 75b6a0a783
commit 8fcabe27fc
38 changed files with 687 additions and 1249 deletions
@@ -0,0 +1,61 @@
+# Plugin releases from GitHub
+
+On **Plugins**, paste a public GitHub repository or release URL into **Import
+from GitHub**. Repository and `/releases/latest` URLs preview the latest stable
+release. Specific `/releases/tag/v3.1.0` links and
+`/releases#release-v3.1.0` links select that exact release, including prereleases.
+
+Review the notes, select a DLL, give the plugin a name, and choose an optional
+T5/T6 game scope. Map scopes can be set on the plugin detail page. **Import only**
+saves the binary; **Import and test** opens the beta builder with that exact
+plugin version selected. Select servers and a test plan to start testing.
+Imports alone never change server files or promote versions.
+
+Each import stores the publisher's tag, release notes, GitHub repository,
+release URL, release and asset IDs, asset filename, publication date and a
+SHA-256 checksum. If GitHub supplies a SHA-256 asset digest, the download must
+match it. The existing upload number still distinguishes different builds.
+Version history links back to each imported release.
+
+## Discovering updates
+
+The plugins page and each plugin's GitHub panel check for the latest stable
+release. Lookups are cached per repository for five minutes, including when
+using **Check for updates**. No background upgrades or automatic promotions
+occur. Failed checks are shown per plugin so one unavailable repository does
+not hide other updates.
+
+**Review update** opens release notes and a DLL picker. The previously imported
+asset filename is selected when available. Multiple unfamiliar DLLs require a
+selection. Importing into an existing plugin keeps its scope and deployment
+filename. An active beta must be completed before another release is imported.
+
+Update tracking follows the most recently imported version's repository and
+asset name. An imported release is distinguished from a promoted release;
+importing the same release asset and binary into that plugin again reuses the
+existing version. An older stable release is not offered as an upgrade over a
+newer imported prerelease. A plugin uploaded manually starts tracking once a
+GitHub release is imported from its detail page.
+
+## Limits
+
+- Public repositories on github.com only; no GitHub credentials are needed.
+- Direct `.dll` release assets up to 64 MB; archives and source-code downloads
+  are not extracted. Other formats can still use the manual upload workflow.
+- Release tags have the same 80-character limit as manually entered versions.
+- GitHub rate limits, missing releases, download failures and checksum failures
+  produce errors without saving a partial import.
+- Downloads follow only HTTPS redirects to GitHub's release asset hosts and
+  have a size limit and timeout.
+
+## API
+
+- `GET /api/plugins/github/release?url=...` previews a release and its DLL assets.
+- `POST /api/plugins/github/import` accepts JSON `{ url, assetId, name,
+  scopeType?, scopeValue? }` for a new plugin, or `{ url, assetId, pluginId }`
+  for an existing plugin. Use the preview's exact release URL, not a mutable
+  `latest` URL. Returns plugin/version IDs, checksum and the beta builder URL.
+- `GET /api/plugins/updates` checks all plugins; `?pluginId=123` checks one.
+
+The server resolves release metadata again during import. Client-supplied notes,
+tags and download URLs are not used as provenance or download instructions.