Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
112 lines (84 loc) · 5.04 KB

CONTRIBUTING.md

File metadata and controls

112 lines (84 loc) · 5.04 KB

Contributing

Thanks for helping build the GoMud Weather Module. This file captures the working agreements that keep the project healthy; the design spec is the authoritative source for what we're building.

Ownership boundary: module vs. GoMud engine

We own the module. Volte6 / the GoMud maintainers own the engine (internal/**) and the module registry. This boundary drives how we work:

Change type Owner Review path
Module code & data (modules/weather/**) Us This repo's normal review.
Any GoMud engine change (internal/**) GoMud Upstream PR + maintainer review.
Registry listing GoMud maintainers One-time onboarding.
DOGMud adapter fixes (on API drift) Us DOGMud repo review.

Guiding principle: keep the engine PR queue empty. v1 is designed to require zero engine changes — everything runs against existing mutator, event, and data-overlay APIs. If a feature seems to need a core change:

  1. First try to express it through existing mechanisms behind the engine/ adapter (mutators, events, the data overlay, exported functions).
  2. Only if there is genuinely no module-side path, propose an upstream change — and present it as additive and backward-compatible, never a hard dependency for the module to function.

See the spec's GoMud core impact & module boundary section for the full capability-by-capability classification.

Out-of-the-box experience is a requirement

A module that needs hand-holding to start doesn't get adopted. Every change must preserve the OOBE bar (spec §2.3):

  • Install + Enabled: true → working weather on a stock world.
  • No required data authoring and no world prep — defaults ship for the standard biomes; the crawler discovers geography from existing exits.
  • Graceful degradation, never a crash. Disabling cleanly self-heals rooms.

If your change adds a knob, it must have a sensible default that keeps OOBE true.

Architecture rules

  • sim/ stays pure. No internal/* imports in the simulation core — an architecture test enforces this. All engine access goes through engine/.
  • All engine-specific calls live in engine/. This is what makes the module portable across GoMud and DOGMud; a future API drift should be a localized patch, not a redesign.
  • Determinism. The sim is driven by a seeded RNG; keep sim.Step a pure function of its inputs so runs stay reproducible and testable.
  • Every package carries a context.md (the GoMud convention — see internal/rooms/context.md, internal/mutators/context.md upstream). It describes the package's overview, key components/structures, core functions, dependencies, consumers, and testing. Add it when you create a package and update it when the package's responsibilities change. Every implementation plan must include a task to create/update the relevant context.md files.

DOGMud backport delta

This module is built for upstream GoMud. The only API that differs in the DOGMud fork is users.UserRecord.SendText: upstream takes (text string); DOGMud takes (category messaging.MessageCategory, text string). All module output goes through the single sendLine helper in weather.go, so backporting to DOGMud is a one-line change: user.SendText(messaging.CategorySystem, text) plus the internal/messaging import. If a future change adds another engine-divergent call, isolate it behind a similar helper rather than scattering it.

Development workflow

Standalone tests (no checkout required)

The pure packages (sim/, crawler/, content/, seasons/) are fully testable in the standalone repo:

go test ./sim/... ./crawler/... ./content/... ./seasons/...

content/ and seasons/ depend on gopkg.in/yaml.v2 — the engine's own YAML library. The standalone go.mod carries it so these tests run without a checkout. The go.mod and go.sum in this repo are never synced to a checkout; the checkout's own dependency graph applies once the module is dropped in.

Engine-coupled tests (require a checkout)

engine/ and the root weather package import internal/* and only compile inside a GoMud checkout. To run the full test suite:

  1. Sync to a checkout: pwsh scripts/sync-to-checkout.ps1 -Checkout <path>.
  2. From the checkout root: go test ./modules/weather/....

Integration / smoke test

  1. Place modules/weather/ under <checkout>/modules/weather/.
  2. go build ./... from the checkout root.
  3. Run the server; first round builds the graph and starts the simulation.
  4. Exercise via weather status, weather fronts, weather spawn, and the player weather command.

Prefer test-first where practical — sim/, crawler/, and content/ are designed to be unit-tested without a running server.

Commits & reviews

  • Keep module and any (rare) engine changes in separate PRs to separate repos — never mix a modules/weather/** change with an internal/** change.
  • Reference the relevant spec section in non-trivial PRs.