开发工作流程

本页面说明 Fess 开发中的标准工作流程。可以学习功能添加、错误修复、测试、代码审查等开发工作的进行方式。

基本开发流程

Fess 的开发按照以下流程进行：

1. 确认・创建 Issue
   ↓
2. 创建分支
   ↓
3. 编码
   ↓
4. 执行本地测试
   ↓
5. 提交
   ↓
6. 推送
   ↓
7. 创建拉取请求
   ↓
8. 代码审查
   ↓
9. 回应审查反馈
   ↓
10. 合并

详细说明各步骤。

Step 1: 确认・创建 Issue

开始开发前，确认 GitHub 的 Issue。

确认现有 Issue

访问 Fess 的 Issue 页面
查找想要处理的 Issue
在 Issue 上评论，告知开始工作

Tip

如果是首次贡献，建议从带有 good first issue 标签的 Issue 开始。

创建新 Issue

对于新功能或错误修复，创建 Issue。

点击 New Issue
选择 Issue 模板
填写必要信息：
- 标题: 简洁明了的说明
- 描述: 详细的背景、预期行为、当前行为
- 重现步骤: 错误的情况
- 环境信息: OS、Java 版本、Fess 版本等
点击 Submit new issue

Issue 示例格式

以下是创建 Issue 时的示例格式。

错误报告:

功能请求:

Step 2: 创建分支

创建工作分支。

分支命名规则

分支名遵循以下格式：

type 的种类:

feature: 添加新功能
fix: 修复错误
refactor: 重构
docs: 更新文档
test: 添加・修改测试

例:

创建分支的步骤

获取最新的 main 分支：
```
git checkout main
git pull origin main
```

创建新分支：

确认分支已创建：
```
git branch
```

Step 3: 编码

进行功能实现或错误修复。

编码规范

Fess 遵循以下编码规范。

基本风格

缩进: 4个空格
行长度: 建议在140字符以内
编码: UTF-8
换行符: LF（Unix 风格）

命名规则

类名: PascalCase（例: SearchService）
方法名: camelCase（例: executeSearch）
常量: UPPER_SNAKE_CASE（例: MAX_SEARCH_SIZE）
变量: camelCase（例: searchResults）

注释

Javadoc: public 的类和方法必需
实现注释: 对复杂的逻辑添加中文或英文说明

例:

/**
 * 执行搜索。
 *
 * @param query 搜索查询
 * @return 搜索结果
 */
public SearchResponse executeSearch(String query) {
    // 规范化查询
    String normalizedQuery = normalizeQuery(query);

    // 执行搜索
    return searchEngine.search(normalizedQuery);
}

null 的处理

尽可能不返回 null
推荐使用 Optional
明确进行 null 检查

例:

// 好的例子
public Optional<User> findUser(String id) {
    return userRepository.findById(id);
}

// 应避免的例子
public User findUser(String id) {
    return userRepository.findById(id);  // null 的可能性
}

异常处理

适当捕获和处理异常
输出日志
向用户提供易懂的消息

例:

日志输出

使用适当的日志级别：

ERROR: 发生错误时
WARN: 应警告的情况
INFO: 重要信息
DEBUG: 调试信息
TRACE: 详细的跟踪信息

例:

开发中的测试

开发期间，通过以下方法进行测试：

本地运行

在 IDE 中运行 org.codelibs.fess.FessBoot 类，确认行为。详情请参阅构建和测试。

调试运行

使用 IDE 的调试器，跟踪代码的运行。

单元测试的执行

执行与更改相关的测试：

详情请参阅构建和测试。

Step 4: 执行本地测试

提交前务必执行测试。

单元测试的执行

集成测试的执行

代码格式检查

执行所有检查

Step 5: 提交

提交更改。

提交消息的规范

提交消息遵循以下格式：

type 的种类:

feat: 新功能
fix: 修复错误
docs: 仅文档更改
style: 不影响代码含义的更改（格式等）
refactor: 重构
test: 添加・修改测试
chore: 构建过程或工具的更改

例:

提交步骤

暂存更改：
```
git add .
```

提交：

确认提交历史：
```
git log --oneline
```

提交粒度

一个提交包含一个逻辑更改
大的更改分成多个提交
提交消息要易懂且具体

Step 6: 推送

将分支推送到远程仓库。

首次推送的情况：

Step 7: 创建拉取请求

在 GitHub 创建拉取请求（PR）。

PR 的创建步骤

访问 Fess 仓库
点击 Pull requests 选项卡
点击 New pull request
选择基础分支（main）和比较分支（工作分支）
点击 Create pull request
填写 PR 内容（按照模板）
点击 Create pull request

PR 示例格式

以下是创建 Pull Request 时的推荐格式。

## 更改内容
此 PR 更改了什么

## 相关 Issue
Closes #123

## 更改类型
- [ ] 新功能
- [ ] 修复错误
- [ ] 重构
- [ ] 更新文档
- [ ] 其他

## 测试方法
如何测试此更改

## 检查清单
- [ ] 代码正常工作
- [ ] 已添加测试
- [ ] 已更新文档
- [ ] 遵循编码规范