Thank you for your interest in contributing to PVE4J! This guide will help you get started.

• Getting Started
• Development Setup
• Code Style
• Testing
• Pull Request Process
• Areas for Contribution

• Java 21 is the default Java version of this project
• Gradle 9.x or higher
• Git
• A Proxmox VE test environment (recommended)

1. Fork the repository on GitHub
2. Clone your fork:

git clone https://github.com/YOUR_USERNAME/PVE4J.git
cd PVE4J

3. Add upstream remote:

git remote add upstream https://github.com/FreshPerf/PVE4J.git

./gradlew build

./gradlew test

./gradlew jar

The JAR will be located in build/libs/.

1. Open IntelliJ IDEA
2. Select "Open" and choose the project directory
3. IntelliJ will automatically detect the Gradle project
4. Wait for dependency resolution to complete

1. Install the Buildship Gradle plugin
2. Import the project as a Gradle project
3. Wait for dependency resolution

1. Install the Java Extension Pack
2. Install the Gradle for Java extension
3. Open the project folder

Follow standard Java naming conventions:

• Classes: PascalCase (e.g., PveQemuVm, ProxmoxRequest)
• Methods: camelCase (e.g., getVersion(), startVm())
• Constants: UPPER_SNAKE_CASE (e.g., MAX_RETRIES)
• Variables: camelCase (e.g., vmid, nodeName)

• Use 4 spaces for indentation (no tabs)
• Maximum line length: 120 characters
• Place opening braces on the same line
• Use meaningful variable names

public class PveQemuVm {
    private final ProxmoxHttpClient client;
    private final String nodeName;
    private final int vmid;
    
    public ProxmoxRequest<PveTask> start() {
        return new ProxmoxRequest<>(() ->
            client.post("nodes/" + nodeName + "/qemu/" + vmid + "/status/start")
                .transformer(new TaskResponseTransformer())
                .execute(PveTask.class)
        );
    }
}

Add JavaDoc comments for all public APIs:

/**
 * Starts the virtual machine.
 * 
 * @return ProxmoxRequest that executes the start operation and returns a PveTask
 */
public ProxmoxRequest<PveTask> start() {
    // implementation
}

Write unit tests for all new functionality using JUnit 5 + Mockito + AssertJ:

import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;

class PveQemuVmTest {
    
    @Test
    void testVmCreation() {
        // Test implementation
        assertNotNull(vm);
        assertEquals(100, vm.vmid());
    }
}

For API operations, use integration tests with a test environment:

@Test
void testStartVM() throws ProxmoxAPIError, InterruptedException {
    // Only runs if test.proxmox.host is set
    String host = System.getProperty("test.proxmox.host");
    if (host == null) {
        return;
    }
    
    Proxmox proxmox = createTestClient();
    PveTask task = proxmox.getNodes()
            .get("test-node")
            .getQemu()
            .get(100)
            .start()
            .execute();
    
    assertNotNull(task.getUpid());
}

# Run all tests
./gradlew test

# Run specific test class
./gradlew test --tests "fr.freshperf.pve4j.ProxmoxTest"

# Run tests matching pattern
./gradlew test --tests "*VM*"

git checkout -b feature/my-new-feature

Use descriptive branch names:

• feature/add-snapshot-support
• bugfix/fix-vm-cloning
• docs/improve-readme

• Write clean, well-documented code
• Add tests for new functionality
• Update documentation if needed
• Follow the code style guidelines

Write clear, descriptive commit messages:

git add .
git commit -m "Add snapshot support for QEMU VMs

- Implement snapshot creation
- Add snapshot deletion
- Add snapshot listing
- Include unit tests
- Update documentation"

git fetch upstream
git rebase upstream/main

git push origin feature/my-new-feature

Then create a PR on GitHub with:

• Title: Clear, descriptive title
• Description: What changes were made and why
• Testing: How you tested the changes
• Related Issues: Link to any related issues

We welcome contributions in these areas:

• More code examples
• Tutorial articles
• Troubleshooting guides

• Increase test coverage
• Integration test improvements
• Mock server for unit tests

• Missing API endpoints
• Asynchronous API improvements
• Reactive programming support

• Builder pattern improvements
• Better error messages
• Validation improvements

• CI/CD improvements
• Performance benchmarks
• Release automation

• Ensure all tests pass
• Update documentation
• Keep PRs focused and small
• Respond to feedback constructively

• Be respectful and constructive
• Focus on the code, not the person
• Explain your suggestions
• Approve when ready

• Questions: Open a GitHub Discussion
• Bugs: Create an Issue
• Chat: Join our community on Discord

By contributing, you agree that your contributions will be licensed under the GNU General Public License v3.0.

Contributors are recognized in:

• CONTRIBUTORS.md file
• Release notes
• Project README

Thank you for contributing to PVE4J!