개발 워크플로우

이 페이지에서는 Fess 개발의 표준 워크플로우를 설명합니다. 기능 추가, 버그 수정, 테스트, 코드 리뷰 등 개발 작업 진행 방법을 배울 수 있습니다.

개발 기본 플로우

Fess 개발은 다음과 같은 흐름으로 진행합니다:

1. Issue 확인·작성
   ↓
2. 브랜치 생성
   ↓
3. 코딩
   ↓
4. 로컬 테스트 실행
   ↓
5. 커밋
   ↓
6. 푸시
   ↓
7. 풀 리퀘스트 작성
   ↓
8. 코드 리뷰
   ↓
9. 리뷰 피드백 대응
   ↓
10. 병합

각 단계에 대해 자세히 설명합니다.

Step 1: Issue 확인·작성

개발을 시작하기 전에 GitHub의 Issue를 확인합니다.

기존 Issue 확인

Fess의 Issue 페이지 에 접속
작업하고 싶은 Issue 찾기
Issue에 코멘트하여 작업 시작 의사 전달

팁

처음 기여하는 경우 good first issue 라벨이 붙은 Issue부터 시작하는 것을 권장합니다.

새로운 Issue 작성

새로운 기능이나 버그 수정의 경우 Issue를 작성합니다.

New Issue 클릭
Issue 템플릿 선택
필요한 정보 기입:
- 제목: 간결하고 알기 쉬운 설명
- 설명: 상세한 배경, 예상되는 동작, 현재 동작
- 재현 절차: 버그의 경우
- 환경 정보: OS, Java 버전, Fess 버전 등
Submit new issue 클릭

Issue 작성 예시

다음은 Issue를 작성할 때의 예시 형식입니다.

버그 리포트:

## 문제 설명
버그에 대한 간결한 설명

## 재현 절차
1. ...
2. ...
3. ...

## 예상되는 동작
본래 어떻게 되어야 하는가

## 실제 동작
현재 어떻게 되고 있는가

## 환경
- OS:
- Java 버전:
- Fess 버전:

기능 요청:

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

## 변경 종류
- [ ] 새 기능
- [ ] 버그 수정
- [ ] 리팩토링
- [ ] 문서 업데이트
- [ ] 기타

## 테스트 방법
이 변경을 어떻게 테스트했는가

## 체크리스트
- [ ] 코드가 동작함
- [ ] 테스트를 추가함
- [ ] 문서를 업데이트함
- [ ] 코딩 규약을 따름