# Contributing to rmcl
Bug reports, fixes, documentation, and themes are welcome. For a larger feature or
architectural change, open an issue first so we can agree on the approach before
you spend time implementing it.
## Reporting bugs
Search the [existing issues](https://github.com/objz/rmcl/issues) before opening a
new one. Include your rmcl version, operating system, steps to reproduce, and what
you expected to happen. For game-launch problems, include the Minecraft version
and mod loader; for TUI problems, include your terminal and a screenshot if useful.
Relevant logs help, but remove tokens, account details, and other private
information before posting them. See the [README](README.md#logs) for log locations.
## Development setup
You need a stable Rust toolchain and a JDK with `javac` and `jar` on `PATH`.
CI uses JDK 21. On Linux, install the libxcb development package (`libxcb1-dev` on
Debian/Ubuntu, `libxcb` on Arch).
Fork the repository and create a branch for your change. The
[source build instructions](README.md#from-source) cover cloning and building.
Run the development version with `cargo run --locked`, or use
`cargo run --locked -- --help` to see the CLI commands.
The main parts of the codebase are:
- `src/cli/`: command-line commands and output.
- `src/config/`: settings, paths, and themes.
- `src/instance/`: instance management, content, modpack imports, loaders, and launches.
- `src/net/`: HTTP requests, downloads, and service API clients.
- `src/tui/`: the terminal interface.
- `tests/`: integration tests; unit tests are under `src/`.
## Making changes
Keep each pull request focused on one fix or feature. Follow the style of nearby
code and reuse existing helpers where they fit. Keep public APIs and new
dependencies limited to what the change needs.
Comments should explain a decision, constraint, or non-obvious behavior. There is
no need to describe what a clearly named function already does. Keep modules
organized by responsibility without splitting files just to meet a size target.
For a bug fix, add a regression test that fails without the fix. For new behavior,
cover the cases that could break. Use test names that describe the scenario and
avoid repeating coverage unless the inputs exercise different behavior.
## Testing
Run the same checks as CI before submitting code changes:
```sh
cargo fmt --all -- --check
cargo build --locked
cargo clippy --all-targets --locked -- -D warnings
cargo test --locked --all-targets
```
Live-service tests are ignored by default. If you run them, note that in the PR,
along with any failures caused by network access or provider credentials.
Check visual and input changes in a real terminal as well as the automated TUI
tests. CI covers Linux, macOS, and Windows; say which platforms you tested locally
and mention anything you could not verify.
## Pull requests
Open your PR against `master`. Explain the problem, summarize the change, link any
related issue, and list the checks you ran. Screenshots or a short recording are
useful for visible TUI changes. Use descriptive commit messages and keep unrelated
changes in separate commits or PRs.
Be available to answer review questions and make follow-up changes. Passing CI
is required before merging, but maintainers may still request changes to the
implementation or scope.
## AI and LLM assistance
AI-assisted contributions are welcome. You are responsible for the code, tests,
and documentation you submit, including anything generated by a tool. Review the
changes yourself, verify the behavior, and be prepared to explain the implementation.
If an LLM helped produce your contribution, disclose it in the PR description.
Name the tool or model, describe which parts it helped with, and say how you
reviewed and tested the result. A short note is enough, for example:
> AI assistance: ChatGPT helped draft the tests. I reviewed the assertions and ran
> the relevant tests locally.
Use your own words in issue reports, PR summaries, and review replies. Maintainers
may close contributions that have not been reviewed or that the author cannot explain.
## License
Contributions are covered by the project's [GPL-3.0-only license](LICENSE).
Only submit code and assets you have the right to contribute under those terms.