Contributing to CraftEngineConverter

Thank you for your interest in contributing to CraftEngineConverter! We welcome contributions from the community to help make this project better.

📋 Table of Contents

Code of Conduct
Getting Started
Development Setup
Project Structure
Coding Standards
Making Changes
Testing
Submitting Changes
Adding New Features
Reporting Bugs

Code of Conduct

By participating in this project, you agree to:

Be respectful and constructive in all interactions
Welcome newcomers and help them get started
Focus on what is best for the community
Show empathy towards other community members

Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

Java Development Kit (JDK) 21 or higher
Apache Maven 3.6+
Git
IntelliJ IDEA (recommended) or another Java IDE

Fork and Clone

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/1robie/CraftEngineConverter.git
cd CraftEngineConverter

Add the upstream repository:

git remote add upstream https://github.com/1robie/CraftEngineConverter.git

Development Setup

Building the Project

Build the entire project:
```
mvn clean install
```
Build without running tests (faster):
```
mvn clean install -DskipTests
```
Build a specific module:
```
cd Plugin
mvn clean package
```

Running Tests

Run all tests:

mvn test

Run tests for a specific module:

cd Common
mvn test

Run a specific test class:

mvn test -Dtest=SnakeUtilsTest

IDE Setup (IntelliJ IDEA)

Open the project in IntelliJ IDEA
The IDE should automatically detect the Maven project and import it
Ensure the Project SDK is set to Java 21:
- File > Project Structure > Project > SDK
Enable annotation processing if not already enabled:
- File > Settings > Build, Execution, Deployment > Compiler > Annotation Processors

Project Structure

The project follows a multi-module Maven structure:

CraftEngineConverter/
├── API/                    # Public API for plugin integration
├── Common/                 # Core conversion logic and utilities
│   ├── cache/             # Caching mechanisms
│   ├── configuration/     # Configuration handling
│   ├── format/            # Format converters
│   ├── packet/            # Packet handling
│   └── tag/               # Tag processing system
├── Hooks/                  # Plugin hook implementations
│   ├── BOM/               # Bill of Materials
│   ├── PacketEvent/       # Packet event integration
│   └── PlaceholderAPI/    # PlaceholderAPI integration
└── Plugin/                 # Main plugin implementation
    ├── command/           # Command implementations
    ├── converter/         # Converter implementations
    ├── loader/            # Plugin loaders
    └── utils/             # Utility classes

Key Components

SnakeUtils: YAML manipulation utility (Common module)
TagProcessor: Custom tag parsing system (Common module)
Converter: Base converter interface and implementations (Plugin module)
CraftEngineImageUtils: Image and glyph conversion (Common module)
ConfigurationManager: Configuration handling (Common module)

Coding Standards

Java Code Style

Java Version: Use Java 21 features where appropriate
Braces: Use K&R style (opening brace on same line)
Naming Conventions:
- Classes: PascalCase
- Methods/Variables: camelCase
- Constants: UPPER_SNAKE_CASE
- Packages: lowercase

Documentation

Add Javadoc comments for all public classes and methods
Use @Contract annotations for null-safety contracts
Use @NotNull and @Nullable annotations appropriately
Include examples in documentation where helpful

Example:

/**
 * Converts a Nexo item configuration to CraftEngine format.
 *
 * @param itemId The unique identifier of the item
 * @param nexoConfig The source Nexo configuration section
 * @return The converted CraftEngine configuration
 * @throws IllegalArgumentException if itemId is null or empty
 */
@Contract("null, _ -> fail")
@NotNull
public ConfigurationSection convertItem(@NotNull String itemId, @NotNull ConfigurationSection nexoConfig) {
    // Implementation
}

Code Quality

Write clean, readable code
Follow SOLID principles
Avoid code duplication (DRY principle)
Use meaningful variable and method names
Handle exceptions appropriately
Add logging for important operations

Null Safety

Always use @NotNull and @Nullable annotations
Use Optional<T> for methods that may return null
Validate input parameters early
Use contracts (@Contract) to document behavior

Making Changes

Branch Naming

Create a descriptive branch name:

feature/add-oraxen-support - for new features
fix/null-pointer-in-converter - for bug fixes
docs/update-readme - for documentation
refactor/simplify-tag-processor - for refactoring

Commit Messages

Follow the conventional commits format:

<type>(<scope>): <subject>

<body>

<footer>

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, etc.)
refactor: Code refactoring
test: Adding or updating tests
chore: Maintenance tasks

Examples:

feat(converter): add Oraxen item conversion support

- Implement OraxenConverter class
- Add item model conversion
- Add texture pack mapping

Closes #42

fix(tag): resolve null pointer in GlyphTagProcessor

Fixed issue where escaped glyphs caused NPE when
PlaceholderAPI was not installed.

Fixes #38

Testing

Writing Tests

Write unit tests for all new functionality
Use JUnit 5 for testing
Place test files in src/test/java mirroring the main package structure
Name test classes with Test suffix (e.g., SnakeUtilsTest)
Use descriptive test method names (e.g., testGetSectionReturnsCorrectValue)

Example test:

@Test
void testConvertItemWithValidInput() {
    // Arrange
    SnakeUtils config = SnakeUtils.createEmpty();
    config.set("material", "DIAMOND_SWORD");
    
    // Act
    ConfigurationSection result = converter.convertItem("test_sword", config.getRoot());
    
    // Assert
    assertNotNull(result);
    assertEquals("DIAMOND_SWORD", result.getString("item"));
}

Test Coverage

Aim for at least 70% code coverage for new code
Test edge cases and error conditions
Test null handling
Test with various input types

Submitting Changes

Pull Request Process

Update your branch:

git fetch upstream
git rebase upstream/main

Ensure all tests pass:
```
mvn clean test
```

Push to your fork:

git push origin feature/your-feature-name

Create a Pull Request on GitHub with:
- Clear title describing the change
- Detailed description of what was changed and why
- Reference to any related issues (e.g., "Closes #123")
- Screenshots for UI changes (if applicable)
Wait for review:
- Address any feedback from reviewers
- Make requested changes in new commits
- Keep the PR updated with upstream changes

Pull Request Checklist

Code follows project coding standards
All tests pass (mvn test)
New tests added for new functionality
Documentation updated (README, Javadoc, etc.)
No compiler warnings introduced
Commit messages follow conventional format
Branch is up-to-date with main
No merge conflicts

Adding New Features

Adding a New Converter

Create a new converter class in Plugin/src/main/java/fr/robie/craftengineconverter/converter/
Extend the Converter interface or appropriate base class
Implement required conversion methods
Add tests in Plugin/src/test/java/
Update documentation

Adding a New Tag Processor

Create processor class in Common/src/main/java/fr/robie/craftengineconverter/common/tag/processor/
Implement TagProcessor interface
Register in TagResolverUtils
Add tests
Document the new tag syntax in README

Adding a New Hook

Create module in Hooks/ directory
Add dependency in pom.xml
Implement hook interface
Add to BOM required to load the hook into Plugin module
Test integration

Reporting Bugs

Before Submitting

Check if the bug has already been reported in Issues
Verify you're using the latest version
Test with minimal configuration to isolate the issue

Bug Report Template

When creating a bug report, include:

Description: Clear description of the issue
Steps to Reproduce:
1. Step one
2. Step two
3. ...
Expected Behavior: What should happen
Actual Behavior: What actually happens
Environment:
- CraftEngineConverter version
- Minecraft version
- Server software (Paper/Folia)
- Java version
- Relevant plugin versions
Logs: Relevant error logs or stack traces
Configuration: Relevant config snippets (sanitized)

Questions?

If you have questions about contributing:

Open a discussion on GitHub
Check existing issues and pull requests
Review the project documentation

License

By contributing to CraftEngineConverter, you agree that your contributions will be licensed under the GPL-3.0 License.

Thank you for contributing to CraftEngineConverter! 🎉

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Contributing to CraftEngineConverter

📋 Table of Contents

Code of Conduct

Getting Started

Prerequisites

Fork and Clone

Development Setup

Building the Project

Running Tests

IDE Setup (IntelliJ IDEA)

Project Structure

Key Components

Coding Standards

Java Code Style

Documentation

Code Quality

Null Safety

Making Changes

Branch Naming

Commit Messages

Testing

Writing Tests

Test Coverage

Submitting Changes

Pull Request Process

Pull Request Checklist

Adding New Features

Adding a New Converter

Adding a New Tag Processor

Adding a New Hook

Reporting Bugs

Before Submitting

Bug Report Template

Questions?

License

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing to CraftEngineConverter

📋 Table of Contents

Code of Conduct

Getting Started

Prerequisites

Fork and Clone

Development Setup

Building the Project

Running Tests

IDE Setup (IntelliJ IDEA)

Project Structure

Key Components

Coding Standards

Java Code Style

Documentation

Code Quality

Null Safety

Making Changes

Branch Naming

Commit Messages

Testing

Writing Tests

Test Coverage

Submitting Changes

Pull Request Process

Pull Request Checklist

Adding New Features

Adding a New Converter

Adding a New Tag Processor

Adding a New Hook

Reporting Bugs

Before Submitting

Bug Report Template

Questions?

License