Contributing to Ansible Crafting¶

Thank you for your interest in contributing to Ansible Crafting! This document provides a quick-start guide for contributors.

Detailed guides: - Development Guide — Building, testing, Gradle tasks, multi-version support - Development Guidelines — Code style, testing standards, Git conventions - Architecture Overview — Package structure, key classes, data flows - Release Process — How releases are managed

Code of Conduct¶

By participating in this project, you agree to abide by our Code of Conduct.

Quick Start¶

Prerequisites¶

• Java 17 (required — the project uses Java 17 language features such as records)
• Git with Conventional Commits
• An IDE (IntelliJ IDEA recommended)

Setup¶

# Clone the repository
git clone https://gitlab.com/starshadow/games/minecraft/minecraft-ansible-crafting.git
cd minecraft-ansible-crafting

# Build and test
./gradlew spotlessApply build --no-configuration-cache   # Linux/macOS
gradlew.bat spotlessApply build --no-configuration-cache  # Windows

# Run the dev client
./gradlew runClient    # Linux/macOS
gradlew.bat runClient  # Windows

For the full development setup guide, see docs/development.md.

How to Contribute¶

Reporting Bugs¶

1. Check if the bug has already been reported in the issue tracker
2. If not, create a new issue with:
3. A clear, descriptive title
4. Steps to reproduce the bug
5. Expected vs. actual behavior
6. Minecraft version and mod version
7. Any relevant logs or screenshots

Suggesting Features¶

1. Check if the feature has already been suggested
2. Create a new issue with the feature request label
3. Describe the feature and why it would be useful

Submitting Code¶

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes following the Development Guidelines
4. Format and test:

   ./gradlew spotlessApply build --no-configuration-cache
   ./gradlew test
   

5. Commit using Conventional Commits:

   feat(scanner): add configurable scan range
   fix(inventory): resolve slot alignment issue
   docs: update configuration reference
   

6. Push to your branch (git push origin feature/amazing-feature)
7. Open a Merge Request

Commit Message Format¶

All commits must follow Conventional Commits, which is required by git-cliff for changelog generation.

<type>(<optional scope>): <description>

See Guidelines — Git Practices for full conventions.

Merge Request Checklist¶

Before submitting your MR, verify:

• [ ] Code compiles without errors (gradlew build`)
• [ ] All tests pass (gradlew test`)
• [ ] Code is formatted (gradlew spotlessCheck`)
• [ ] Commit messages follow Conventional Commits
• [ ] No empty mixin stubs (see Guidelines — Mixin Guidelines)
• [ ] Documentation updated if adding features
• [ ] Changes are logically grouped into atomic commits

Project Structure¶

src/main/java/com/ansiblecrafting/
├── AnsibleCraftingMod.java    # Main mod entry point
├── client/                     # Client-only code
│   └── ui/                     # UI components
├── config/                     # Configuration
├── crafting/                   # Crafting logic
├── integration/                # Mod integrations (EMI, REI)
├── inventory/                  # Inventory scanning
├── mixin/                      # Mixin classes
└── network/                    # Networking packets

For a deeper dive, see Architecture Overview.

Testing¶

The project uses JUnit 5. Tests mirror the source structure in src/test/java/.

./gradlew test                                              # Run all tests
./gradlew test --tests "com.ansiblecrafting.config.*"       # Run specific package
./gradlew test --info                                       # Verbose output

See Development Guide — Testing for conventions and examples.

License¶

By contributing to Ansible Crafting, you agree that your contributions will be licensed under the Mozilla Public License 2.0. Per MPL-2.0 Section 2.1, contributors automatically grant a worldwide, royalty-free license for their contributions. No separate Contributor License Agreement (CLA) is required.

All source files must include the MPL-2.0 license header. Run ./gradlew spotlessApply to automatically add or verify headers. See LICENSE for the full license text.

Questions?¶

Open an issue or reach out to the maintainer at ghent@starshadow.com.