Contributing

Contributing

Contributions and bug reports are welcome. This page covers the mechanics; see Building from Source for the dev-environment setup.

Before you start

• Search the issue tracker for an existing report or request before opening a new one.
• For anything beyond a trivial fix, open an issue first so the approach can be agreed before code is written.

Branch & PR workflow

• Work on a branch — never commit directly to main.
• Branch names: dev/<short-feature-slug> (kebab-case).
• Commit messages follow Conventional Commits: feat:, fix:, docs:, chore:, refactor:, test:, perf:, ci:.
• Open a Pull Request against main with a conventional-commit-style title. PRs are squash-merged to keep history clean.
• Bump mod_version in gradle.properties per SemVer — PATCH during development, MINOR when a feature merges.

What a change must satisfy

• ./gradlew build passes for all three loaders.
• ./gradlew :common:test passes (add tests for new distribution logic).
• Anything touching the loot mixin, the StatsModifier API, the attribute-modifier logic, or the distribution parameters is verified on Fabric and NeoForge dev clients, plus a Forge production-jar smoke test (Forge runClient is blocked by an upstream issue — see Building from Source).
• Keep the public API surface limited to the games.brennan.adventureitemstats.api package; internal.* and mixin.* are not API.

Releasing

Releases are automated and dispatch-only. The release.yml workflow is the single source of git tags — never run git tag by hand.

The flow, in brief:

1. Make sure mod_version on main is the version you want to ship.
2. Dispatch the workflow with a matching tag:

   gh workflow run release.yml -f tag=v<version>

3. The workflow verifies the tag matches mod_version, builds all three loader jars, creates the GitHub Release (pre-1.0 → marked beta/pre-release), and publishes to Modrinth and CurseForge (skipping a platform if its token/ID isn't configured).

Platform setup (Modrinth/CurseForge project creation, tokens, and variables) is documented in the in-repo docs/PUBLISHING.md.

License

By contributing you agree your contributions are licensed under the project's PolyForm Shield 1.0.0 license.