# Contributing: Workflow

> End-to-end workflow for opening issues, implementing changes, validating them, and preparing pull requests in Kore.

Updated 2026-10-02. Canonical: https://kore.ayfri.com/docs/contributing/contributing-workflow

This page is the *process reference* for changes in Kore.

Use it when you already know **what** you want to change and need to validate **how** to carry that change from issue to
PR.

## 1) Qualify the issue or proposal first

Before writing code, make sure the scope is explicit.

If you are opening an issue:

- Pick the closest template in [`.github/ISSUE_TEMPLATE`](https://github.com/ayfri/kore/tree/master/.github/ISSUE_TEMPLATE).
- Search for duplicates first.
- Include a minimal reproduction or explicit reproduction steps.
- Include expected behavior, actual behavior, and the Kore + Minecraft versions you tested.

If you are starting from an existing issue or drafting a PR directly:

- Keep the first pass focused on one behavior change.
- Pick the narrowest module scope possible.
- Read one similar merged change before adding new abstractions.

Useful scope labels when triaging work:

| Scope             | Use it for                                           |
|-------------------|------------------------------------------------------|
| `bindings`        | Datapack importer and generated bindings output      |
| `dsl`             | Command DSL and data-driven `kore` APIs              |
| `generation`      | Source-data processing and code generation pipelines |
| `helpers` / `oop` | Higher-level APIs built on top of the core DSL       |
| `update`          | Minecraft version tracking and update work           |
| `website`         | Documentation content and docs site behavior         |

## 2) Trace the change before editing

Before implementation:

- Confirm the target module in [Contributing: Architecture and Patterns](https://kore.ayfri.com/docs/contributing/architecture-and-patterns.md).
- Identify symbol usages and nearby call paths.
- Reuse an existing helper, serializer, or feature pattern when one already exists.

This is the fastest way to avoid duplicate APIs and hidden coupling.

If the change is a new data-driven feature in `kore`, use [Contributing: Creating a New Generator](https://kore.ayfri.com/docs/contributing/creating-a-new-generator.md)
instead of inventing a new shape from scratch.

## 3) Implement with tests and docs in the same pass

For `bindings` and `kore`, tests are expected alongside code changes.

Test locations, per module (all four modules are Kotlin Multiplatform - see
[Multiplatform Support](https://kore.ayfri.com/docs/advanced/multiplatform.md)):

- `commonTest` for specs that build a `dataPack { }` in memory and assert JSON/command output; these run on the JVM,
  Node.js, and a headless browser.
- `jvmTest` for specs that need real file I/O (`generate()`, `generateZip()`) or a JVM-only dependency.

For example, [`bindings/src/commonTest/kotlin/io/github/ayfri/kore/bindings`](https://github.com/ayfri/kore/tree/master/bindings/src/commonTest/kotlin/io/github/ayfri/kore/bindings) and
[`kore/src/commonTest/kotlin/io/github/ayfri/kore`](https://github.com/ayfri/kore/tree/master/kore/src/commonTest/kotlin/io/github/ayfri/kore).

At minimum, validate:

- Output behavior for commands or generated resources.
- Regression behavior for bugs.
- Serialization or deserialization shapes when JSON/NBT is involved.

Any user-visible behavior change should update docs in [`website/src/jsMain/resources/markdown/doc`](https://github.com/ayfri/kore/tree/master/website/src/jsMain/resources/markdown/doc).

Documentation updates usually include:

- A usage-oriented example when the feature is public.
- A migration note or caveat when behavior changed.
- Updated internal links when contributor navigation should change.

## 4) Validate locally before opening the PR

Run the checks that match the modules you changed.

Typical commands:

- `./gradlew :bindings:jvmTest` for `bindings` changes, fast JVM-only iteration.
- `./gradlew :kore:jvmTest` for core DSL changes, fast JVM-only iteration.
- `./gradlew :oop:jvmTest` for OOP module changes, fast JVM-only iteration.
- `./gradlew :helpers:jvmTest` for helpers module changes, fast JVM-only iteration.
- `./gradlew testAll` before opening the PR, to also run every module's Node.js and browser (Karma) test tasks.
- Your local website workflow when you touched docs navigation or page structure.

Validation checklist:

- Docs reflect the final API or DSL shape.
- Generated outputs were **not** edited by hand.
- Manual lists and registries still follow project ordering conventions.
- Tests cover the changed behavior.

## 5) Prepare a reviewable pull request

A good Kore PR is easy to review because it stays narrow and links the right context.

In the PR body, link:

- The docs pages updated in the same PR.
- The issue or proposal being solved.
- The tests that cover the change.
- Any migration impact or behavior caveat for existing users.

For the title and commit messages, follow conventional commits. Common examples:

- `chore(minecraft): Increase Minecraft version to X.Y.Z.`
- `chore(project): Increase project version to X.Y.Z.`
- `feat(code): Update project to Minecraft version X.Y.Z.`

## 6) Frequent review blockers

- Editing generated output instead of updating the generator or source pipeline.
- Mixing refactors and feature behavior changes in one large PR.
- Re-implementing a serializer or helper that already exists.
- Shipping an API change without matching documentation.

## See also

- [Contributing: Architecture and Patterns](https://kore.ayfri.com/docs/contributing/architecture-and-patterns.md)
- [Contributing: Contributing](https://kore.ayfri.com/docs/contributing/contributing.md)
- [Contributing: Creating a New Generator](https://kore.ayfri.com/docs/contributing/creating-a-new-generator.md)
- [Contributing: CI/CD and Releases](https://kore.ayfri.com/docs/contributing/ci-cd-and-releases.md)
- [Multiplatform Support](https://kore.ayfri.com/docs/advanced/multiplatform.md)