Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
321 lines (234 loc) · 7.27 KB

CONTRIBUTING.md

File metadata and controls

321 lines (234 loc) · 7.27 KB

Contributing to Assistant Agent

Thank you for your interest in contributing to Assistant Agent! We welcome contributions from the community.

Table of Contents

Code of Conduct

Please be respectful and constructive in all interactions. We are committed to providing a welcoming and inclusive environment for everyone.

Getting Started

Prerequisites

  • Java 17+ (OpenJDK or GraalVM)
  • Maven 3.8+
  • Git
  • IDE: IntelliJ IDEA (recommended) or Eclipse

Quick Setup

# Clone the repository
git clone https://github.com/spring-ai-alibaba/AssistantAgent.git
cd AssistantAgent

# Build the project
mvn clean install -DskipTests

# Run tests
mvn test

Development Environment

IDE Setup (IntelliJ IDEA)

  1. Import Project: File → Open → Select pom.xml
  2. Configure JDK: File → Project Structure → SDK → Java 17+
  3. Enable Annotation Processing: Settings → Build → Compiler → Annotation Processors → Enable

Environment Variables

Create a .env file (not committed to Git) or set environment variables:

export DASHSCOPE_API_KEY=your-api-key-here

Running the Application

cd assistant-agent-start
mvn spring-boot:run

How to Contribute

Types of Contributions

Type Description
🐛 Bug Fix Fix issues in existing code
✨ Feature Add new functionality
📝 Documentation Improve docs, README, comments
🧪 Tests Add or improve tests
🔧 Refactor Improve code quality without changing behavior
🌐 Translation Help with i18n

Contribution Workflow

  1. Check existing issues - Look for similar issues or discussions
  2. Open an issue - For significant changes, discuss first
  3. Fork & Clone - Fork the repo and clone locally
  4. Create a branch - Branch from main
  5. Make changes - Follow code style guidelines
  6. Test - Ensure all tests pass
  7. Commit - Write clear commit messages
  8. Push & PR - Open a Pull Request
# Fork on GitHub, then:
git clone https://github.com/YOUR_USERNAME/AssistantAgent.git
cd AssistantAgent
git checkout -b feature/your-feature-name

# Make changes...
mvn test
git add .
git commit -m "feat: add your feature"
git push origin feature/your-feature-name

# Open PR on GitHub

Code Style

Java Conventions

  • Follow Google Java Style Guide
  • Use 4 spaces for indentation (not tabs)
  • Maximum line length: 120 characters
  • Use meaningful variable and method names

Javadoc Requirements

All public APIs must have Javadoc:

/**
 * Brief description of the method.
 *
 * <p>Additional details if needed.
 *
 * @param paramName Description of the parameter
 * @return Description of return value
 * @throws ExceptionType When this exception is thrown
 * @since 1.0.0
 */
public ReturnType methodName(ParamType paramName) {
    // implementation
}

Logging Format

Follow the project logging convention:

// Format: ClassName#methodName - reason=description
logger.info("GraalCodeExecutor#execute - 执行函数: functionName={}, args={}", functionName, args);
logger.error("SearchProvider#search - 搜索失败: query={}, error={}", query, e.getMessage());

Package Structure

com.alibaba.assistant.agent
├── common          # Shared utilities, constants, interfaces
├── core            # Core execution engine
├── evaluation      # Evaluation framework
├── prompt          # Prompt building
├── extension       # Extension modules
│   ├── experience  # Experience management
│   ├── learning    # Learning extraction
│   ├── search      # Search providers
│   ├── reply       # Reply channels
│   ├── trigger     # Trigger mechanism
│   └── dynamic     # Dynamic tools (MCP, HTTP)
└── autoconfigure   # Spring Boot auto-configuration

License Header

All source files must include the Apache 2.0 license header:

/*
 * Copyright 2024-2025 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

Testing

Test Requirements

  • Unit tests required for all new features
  • Maintain existing tests - Don't break existing functionality
  • Target coverage: Aim for > 60% coverage on new code

Running Tests

# Run all tests
mvn test

# Run specific test class
mvn test -Dtest=ClassName

# Run with coverage report
mvn test jacoco:report

Test Naming Convention

@Test
void shouldReturnSuccessWhenValidInput() { ... }

@Test
void shouldThrowExceptionWhenInputIsNull() { ... }

Pull Request Process

Before Submitting

  • Code compiles without errors
  • All tests pass
  • New code has appropriate tests
  • Javadoc added for public APIs
  • No sensitive information (API keys, etc.)
  • Commit messages are clear

PR Title Format

Use Conventional Commits:

feat: add new search provider for Elasticsearch
fix: resolve null pointer in experience retrieval
docs: update README with configuration examples
refactor: simplify prompt builder logic
test: add unit tests for trigger module

PR Description Template

## Description
Brief description of changes.

## Related Issue
Fixes #123

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Code follows style guidelines

Review Process

  1. Maintainers will review your PR
  2. Address any requested changes
  3. Once approved, maintainers will merge
  4. Your contribution will be included in the next release!

Issue Guidelines

Bug Reports

Include:

  • Clear description of the bug
  • Steps to reproduce
  • Expected vs actual behavior
  • Environment details (OS, Java version)
  • Relevant logs/screenshots

Feature Requests

Include:

  • Clear description of the feature
  • Use case / motivation
  • Proposed solution (optional)
  • Alternatives considered (optional)

Getting Help

  • Questions: Open a Discussion on GitHub
  • Bugs: Open an Issue with the bug template
  • Features: Open an Issue with the feature template

Recognition

Contributors will be recognized in:

  • Release notes
  • Contributors list

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.