Contribution Guidelines

Thank you for your interest in contributing to Spring AI Watsonx.ai! This document provides guidelines and instructions for contributing to the project.

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

How to Contribute

Reporting Issues

Before creating a new issue, please:

Search existing issues to avoid duplicates
Use the issue template when available
Provide clear reproduction steps
Include relevant version information

Submitting Pull Requests

Fork the repository and create your branch from main
Follow coding standards - maintain consistent style with existing code
Write tests - ensure your changes are covered by tests
Update documentation - document new features and API changes
Sign commits - use git commit -s to sign your commits
Create a pull request with a clear description of changes

Development Setup

Prerequisites

JDK 17 or later
Maven 3.9+
Git

Building the Project

git clone https://github.com/spring-ai-community/spring-ai-watsonx-ai.git
cd spring-ai-watsonx-ai
mvn clean install

Running Tests

# Run all tests
mvn test

# Run specific test class
mvn test -Dtest=WatsonxAiChatModelTest

# Run integration tests (requires API credentials)
mvn verify -Pintegration-tests

Building Documentation

cd docs
mvn clean package

The generated documentation will be in docs/target/antora/site.

Coding Standards

Java Code Style

Follow standard Java conventions
Use meaningful variable and method names
Keep methods focused and concise
Add JavaDoc for public APIs
Use @Override annotations
Prefer composition over inheritance

Code Formatting

The project uses standard Java formatting. Configure your IDE:

Indentation: 4 spaces (no tabs)
Line length: 120 characters
Organize imports automatically

Testing Guidelines

Write unit tests for all new functionality
Use descriptive test method names
Follow the Arrange-Act-Assert pattern
Mock external dependencies
Aim for high code coverage (>80%)

Example test structure:

@Test
void shouldGenerateResponseWithValidPrompt() {
    // Arrange
    String prompt = "Hello, world!";
    WatsonxAiChatModel chatModel = createChatModel();

    // Act
    String response = chatModel.call(prompt);

    // Assert
    assertThat(response).isNotNull();
    assertThat(response).isNotEmpty();
}

Documentation Guidelines

AsciiDoc Format

Use AsciiDoc for all documentation
Follow existing document structure
Include code examples where appropriate
Add cross-references to related topics
Keep language clear and concise

Documentation Structure

docs/
├── src/main/antora/
│   ├── modules/ROOT/
│   │   ├── pages/
│   │   │   ├── index.adoc
│   │   │   ├── getting-started/
│   │   │   ├── api/
│   │   │   ├── concepts/
│   │   │   └── ...
│   │   └── nav.adoc
│   └── antora-playbook.yml

Commit Message Guidelines

Follow conventional commit 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

Example:

feat(chat): add streaming support for chat responses

Implement streaming API for real-time chat responses using
Server-Sent Events (SSE). This allows clients to receive
partial responses as they are generated.

Closes #123