13315423919/LandPPT

Template

Fork 0

Files

13315423919 12dfeab392 Add File

2025-11-07 09:05:56 +08:00

8.9 KiB

Raw Blame History

贡献指南 / Contributing Guide

English | 中文

中文

感谢您对 LandPPT 项目的关注！我们欢迎所有形式的贡献，包括但不限于：

🤝 贡献方式

🐛 Bug 报告：发现问题并报告
💡 功能建议：提出新功能想法
📝 代码贡献：修复bug或实现新功能
📚 文档改进：完善文档和示例
🌐 翻译工作：帮助翻译界面和文档
🧪 测试用例：编写和改进测试

🚀 开始贡献

1. 准备开发环境

# Fork 并克隆仓库
git clone https://github.com/your-username/LandPPT.git
cd LandPPT

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# 或
.venv\Scripts\activate     # Windows

# 安装依赖
pip install uv
uv pip install -e ".[dev]"

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件配置必要的API密钥

# 初始化数据库
python setup_database.py

# 运行项目
python run.py

2. 开发流程

创建分支

git checkout -b feature/your-feature-name
# 或
git checkout -b fix/your-bug-fix

编写代码
- 遵循现有的代码风格
- 添加必要的注释和文档字符串
- 确保代码通过所有测试

运行测试

# 运行所有测试
pytest

# 运行特定测试
pytest tests/test_specific.py

# 生成覆盖率报告
pytest --cov=src/landppt

代码格式化

# 格式化代码
black src/
isort src/

# 检查代码质量
flake8 src/
mypy src/

提交更改

git add .
git commit -m "feat: add new feature description"
# 或
git commit -m "fix: fix bug description"

推送并创建PR
```
git push origin feature/your-feature-name
```
然后在GitHub上创建Pull Request

📝 代码规范

提交信息格式

使用 Conventional Commits 格式：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

类型包括：

feat: 新功能
fix: Bug修复
docs: 文档更新
style: 代码格式化
refactor: 代码重构
test: 测试相关
chore: 构建过程或辅助工具的变动

Python代码规范

遵循 PEP 8 规范
使用类型提示 (Type Hints)
编写清晰的文档字符串
保持函数和类的单一职责

示例代码风格

from typing import Optional, Dict, Any
import logging

logger = logging.getLogger(__name__)

class PPTGenerator:
    """PPT生成器类
    
    负责根据输入内容生成PPT演示文稿
    """
    
    def __init__(self, config: Dict[str, Any]) -> None:
        """初始化PPT生成器
        
        Args:
            config: 配置字典
        """
        self.config = config
        
    async def generate_ppt(
        self, 
        content: str, 
        template_id: Optional[str] = None
    ) -> Dict[str, Any]:
        """生成PPT
        
        Args:
            content: 输入内容
            template_id: 模板ID，可选
            
        Returns:
            生成的PPT数据
            
        Raises:
            ValueError: 当输入内容为空时
        """
        if not content.strip():
            raise ValueError("内容不能为空")
            
        logger.info(f"开始生成PPT，内容长度: {len(content)}")
        
        # 实现逻辑...
        return {"status": "success", "data": {}}

🧪 测试指南

编写测试

为新功能编写单元测试
确保测试覆盖率不低于80%
使用有意义的测试名称
测试边界条件和异常情况

测试示例

import pytest
from unittest.mock import Mock, patch
from src.landppt.core.ppt_generator import PPTGenerator

class TestPPTGenerator:
    """PPT生成器测试类"""
    
    @pytest.fixture
    def generator(self):
        """创建PPT生成器实例"""
        config = {"template_dir": "/tmp/templates"}
        return PPTGenerator(config)
    
    async def test_generate_ppt_success(self, generator):
        """测试成功生成PPT"""
        content = "这是测试内容"
        result = await generator.generate_ppt(content)
        
        assert result["status"] == "success"
        assert "data" in result
    
    async def test_generate_ppt_empty_content(self, generator):
        """测试空内容异常"""
        with pytest.raises(ValueError, match="内容不能为空"):
            await generator.generate_ppt("")

📋 Issue 和 PR 模板

Bug 报告

报告bug时请包含：

问题描述
复现步骤
期望行为
实际行为
环境信息（操作系统、Python版本等）
相关日志或截图

功能请求

提出新功能时请包含：

功能描述
使用场景
预期收益
可能的实现方案

🎯 开发重点

当前项目重点关注以下方面：

AI集成优化
- 支持更多AI提供商
- 优化AI调用性能
- 改进错误处理
模板系统
- 丰富模板库
- 改进模板编辑器
- 支持自定义模板
用户体验
- 优化Web界面
- 改进响应速度
- 增强错误提示
文档和测试
- 完善API文档
- 增加测试覆盖率
- 改进用户指南

📞 联系方式

如有疑问，可以通过以下方式联系：

创建 GitHub Issue
参与 GitHub Discussions

English

Thank you for your interest in the LandPPT project! We welcome all forms of contributions, including but not limited to:

🤝 Ways to Contribute

🐛 Bug Reports: Find and report issues
💡 Feature Suggestions: Propose new feature ideas
📝 Code Contributions: Fix bugs or implement new features
📚 Documentation: Improve docs and examples
🌐 Translation: Help translate interface and documentation
🧪 Testing: Write and improve test cases

🚀 Getting Started

1. Development Environment Setup

# Fork and clone the repository
git clone https://github.com/your-username/LandPPT.git
cd LandPPT

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# or
.venv\Scripts\activate     # Windows

# Install dependencies
pip install uv
uv pip install -e ".[dev]"

# Configure environment variables
cp .env.example .env
# Edit .env file to configure necessary API keys

# Initialize database
python setup_database.py

# Run the project
python run.py

2. Development Workflow

Create Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

Write Code
- Follow existing code style
- Add necessary comments and docstrings
- Ensure code passes all tests

Run Tests

# Run all tests
pytest

# Run specific tests
pytest tests/test_specific.py

# Generate coverage report
pytest --cov=src/landppt

Code Formatting

# Format code
black src/
isort src/

# Check code quality
flake8 src/
mypy src/

Commit Changes

git add .
git commit -m "feat: add new feature description"
# or
git commit -m "fix: fix bug description"

Push and Create PR
```
git push origin feature/your-feature-name
```
Then create a Pull Request on GitHub

📝 Code Standards

Commit Message Format

Use Conventional Commits format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types include:

feat: New feature
fix: Bug fix
docs: Documentation update
style: Code formatting
refactor: Code refactoring
test: Test related
chore: Build process or auxiliary tool changes

Python Code Standards

Follow PEP 8 guidelines
Use Type Hints
Write clear docstrings
Maintain single responsibility for functions and classes

🧪 Testing Guidelines

Writing Tests

Write unit tests for new features
Ensure test coverage is not less than 80%
Use meaningful test names
Test boundary conditions and exceptions

📋 Issue and PR Templates

Bug Reports

When reporting bugs, please include:

Problem description
Steps to reproduce
Expected behavior
Actual behavior
Environment info (OS, Python version, etc.)
Relevant logs or screenshots

Feature Requests

When proposing new features, please include:

Feature description
Use cases
Expected benefits
Possible implementation approaches

📞 Contact

If you have questions, you can contact us through:

Create a GitHub Issue
Join GitHub Discussions

Thank you for contributing to LandPPT! 🎉

8.9 KiB Raw Blame History Unescape Escape