wtclaude
48b16dc70e
"## Deploy" led with deploy.ps1 and mentioned the installer only afterwards, which is backwards now that the installer is released. - Deploy leads with the installer, with the by-hand overlay copy (INSTALL.md Appendix A2) as the supported alternative. - deploy.ps1 gets its own subsection as the developer path: it deploys from a working tree, which is the one thing the installer cannot do, and it installs no sidecar and checks no protocol pairing. - CONTRIBUTING: note that changes reach shards through a release, so a change that only works when deploy.ps1 copies it does not ship. Co-Authored-By: Claude <noreply@anthropic.com>
103 lines
4.4 KiB
Markdown
103 lines
4.4 KiB
Markdown
# Contributing to Runic Gateway — ServUO Plugin
|
|
|
|
Thanks for your interest in contributing! This repo is the **C# ServUO side** of
|
|
the game bridge. The shard emits newline-delimited JSON over a loopback TCP
|
|
socket to the Rust sidecar
|
|
([RunicGateway/link](https://gitea.whitlocktech.com/RunicGateway/link)).
|
|
|
|
By participating you agree to abide by our
|
|
[Code of Conduct](CODE_OF_CONDUCT.md).
|
|
|
|
## Ways to contribute
|
|
|
|
- **Report a bug** or **request a feature** through the
|
|
[issue tracker](https://gitea.whitlocktech.com/RunicGateway/servuo-plugins/issues)
|
|
(issue templates are provided).
|
|
- **Improve the code or docs** by opening a pull request (see below).
|
|
- **Never** report a security vulnerability in a public issue — see
|
|
[SECURITY.md](SECURITY.md).
|
|
|
|
## Development setup
|
|
|
|
This plugin is deployed as **source** and compiled by ServUO at boot — there is
|
|
no standalone build artifact and no CI build (it needs the ServUO reference
|
|
assemblies to compile). See the [README](README.md) for the full model.
|
|
|
|
**Key rule:** anything under `overlay/` is authoritative and mirrors the ServUO
|
|
server root. **Do not edit files in a deployed server tree directly** — edit here
|
|
under `overlay/` (or `patches/` for changes to stock ServUO files) and deploy:
|
|
|
|
```powershell
|
|
# Show what would change, then write it into a ServUO install:
|
|
.\deploy.ps1 -ServerPath C:\path\to\servuo -Verify
|
|
.\deploy.ps1 -ServerPath C:\path\to\servuo
|
|
```
|
|
|
|
`deploy.ps1` deploys from *this working tree*, which is what you want while
|
|
developing. It is not how a shard is set up: operators run the
|
|
[Runic Gateway installer](https://gitea.whitlocktech.com/RunicGateway/installer),
|
|
which syncs the released overlay tarball and installs the sidecar alongside it.
|
|
Changes here reach shards through a [release](README.md#releases), so a change
|
|
that only works when `deploy.ps1` copies it is a change that does not ship.
|
|
|
|
- `overlay/` — copied over an install (the only thing `deploy.ps1` deploys).
|
|
- `patches/` — unified diffs against stock ServUO for files we must modify.
|
|
- `tools/` — never deployed: test scaffolding and stub sidecars.
|
|
|
|
### Testing
|
|
|
|
`tools/stub_sidecar.ps1` is a loopback listener that logs every line the shard
|
|
sends — run it, boot the shard, and watch events arrive:
|
|
|
|
```powershell
|
|
.\tools\stub_sidecar.ps1 -Port 7788 -Log .\sidecar.log
|
|
```
|
|
|
|
`tools/stub_sidecar_request.ps1` additionally sends inbound requests to exercise
|
|
the request/response handlers. For real end-to-end testing, run against the Rust
|
|
sidecar rather than the throwaway PowerShell stubs.
|
|
|
|
### Protocol compatibility
|
|
|
|
The loopback JSON protocol is a **compatibility contract** shared with the
|
|
sidecar. The canonical event/command catalog lives in the
|
|
[docs repo](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link)
|
|
(`PLAN.md` §5/§7 and `INTEGRATION.md`). If you add or change an event or command,
|
|
keep the plugin, the sidecar, and the spec in sync.
|
|
|
|
## Branch & PR workflow
|
|
|
|
1. Branch from `main` with a descriptive name
|
|
(`feature/…`, `fix/…`, `docs/…`, `chore/…`).
|
|
2. Keep changes focused; small PRs are easier to review.
|
|
3. Push and open a pull request against `main`. Fill out the PR template,
|
|
including the **AI-assisted contributions** disclosure.
|
|
4. A maintainer will review; address feedback with follow-up commits.
|
|
|
|
### Commit messages
|
|
|
|
We use [Conventional Commits](https://www.conventionalcommits.org/) —
|
|
`type(scope): summary` (e.g. `feat(bridge): add vendor.sale event`).
|
|
|
|
## AI-assisted contributions (disclosure required)
|
|
|
|
This project is developed openly with AI assistance, and we ask the same
|
|
transparency of everyone. **If you used an AI tool** (Claude, Copilot, ChatGPT,
|
|
Cursor, etc.) to help produce a contribution, you must disclose it:
|
|
|
|
- Tick the AI-usage box in the pull-request template and name the tool(s).
|
|
- Mark AI-authored commits with a trailer, e.g.
|
|
`Co-Authored-By: Claude <noreply@anthropic.com>` or `Assisted-By: <tool>`.
|
|
- You remain responsible for every line you submit: review it, understand it,
|
|
and make sure it is correct and that you have the right to contribute it.
|
|
|
|
Disclosed AI assistance is welcome. Undisclosed AI-generated contributions are
|
|
not, and may be closed.
|
|
|
|
## License
|
|
|
|
Runic Gateway is licensed under the **GNU General Public License v3.0 or later**
|
|
(see [LICENSE.md](LICENSE.md)). By submitting a contribution you agree that it is
|
|
licensed under the same terms (inbound = outbound) and that you have the right to
|
|
contribute it.
|