CUBRID는 오픈소스 프로젝트로, 일반적인 오픈소스 프로젝트 개발 프로세스를 기반으로 운영합니다. CUBRID의 개발자들은 오픈소스 개발 프로젝트를 위한 협업 도구를 이용해 CUBRID라는 하나의 큰 프로젝트에 함께 기여하고 있습니다.

이 문서는 협업 도구를 활용한 개발 워크 플로우를 설명하고 개발 문화에 대한 상호 합의를 위한 기본 원칙 수립 목적으로 작성되었습니다. 이 문서를 기반으로 상호 간의 합의로 상황에 따라 유연하게 적용하고, 문서를 수정/발전 시켰으면 합니다.

• 공정과 도구보다 개인의 상호작용을

• 포괄적인 문서보다 작동하는 소프트웨어를

• 계획에 따르기보다 변화에 대응하기를

CUBRID 개발 프로세스는 다음 두 도구를 기반으로 운영됩니다.

• Issue Tracking: JIRA (jira.cubrid.org)

• Code Repository and Code Review: Github (github.com/CUBRID)

CUBRID의 모든 프로젝트, 기능추가, 버그수정은 JIRA 이슈 생성으로부터 시작합니다. JIRA의 Issue workflow에 따라 문제를 정의, 분석하는 단계를 지나 설계 및 구현을 시작하게 됩니다. 설계 및 구현 단계에서는 Github에서 브랜치 생성, Pull Request, 코드 리뷰를 통해 검토/검증 과정을 거친 후 CUBRID에 코드를 반영합니다. 위 과정을 계속 반복하여 CUBRID를 계속 발전시킵니다.

이 문서는 전체 개발 프로세스를 JIRA, Github, 머지 후 상황으로 나누어 각각의 워크플로우를 설명합니다. 큐브리드 프로젝트에 기여하기 전에 문서 전체를 한 번 필독을 권장합니다. 그리고 개발 프로세스를 진행하면서 프로세스의 각 단계마다 해당 섹션의 가이드를 참조합니다.

큐브리드는 JIRA를 사용하여 프로젝트를 관리하며 모든 변경사항은 이슈를 단위로 하여 관리 합니다. JIRA 이슈는 진행 상황에 따라 위 그림과 같이 9가지의 상태 (OPEN, CONFIRMED, ANALYSIS, DEVELOP, HANDOVER, BACKPORT, RESOLVED, TEST, CLOSED) 를 가지며, 이슈 진행 상황에 따라 상태를 변경하여 관리합니다. 처음 이슈를 생성하면 “OPEN” 이고, “CLOSED” 로 모든 기여 작업이 완료됩니다.‌

각 상태에서 이슈를 진행하는 주체는 다를 수 있습니다.

예를 들어 “OPEN” 상태에서는 프로젝트 메인테이너가 해당 이슈에 대해 선별 작업(triage) 후 승인된 이슈에 대해 개발자 지정과 함께 “CONFIRMED”상태로 할당합니다. "ANALYSIS" 상태는 개발자가 할당 받은 이슈를 분석하는 단계로 분석, 설계, POC 및 설계의 동료 리뷰 등의 개발 전 분석 작업을 진행합니다. "DEVELOP" 상태는 분석된 내용을 기반으로 개발, 동료 리뷰 , 단위 테스트 및 코드 머지을 진행합니다. "HANDOVER" 상태는 품질보증팀(QA)에 이관하기 위한 사전 작업을 하는 단계로 테스트 시나리오 정리, 매뉴얼 작성 및 regression test 수정 작업을 진행합니다. “RESOLVED” 상태에서는 QA 메인테이너가 이슈를 테스트 담당자에게 할당합니다. 지정된 테스트 담당자는 "TEST"로 상태 변경 후 QA 업무를 수행합니다. "BACKPORT" 상태는 하위 버전에 테스트 완료된 이슈의 코드 및 매뉴얼을 반영합니다.

단, 프로젝트 메인테이너는 모든 상태에서 내용과 이슈 상태 전환과 같은 수정이 가능합니다.

문서 이력

프로젝트 메인테이너는 “OPEN” 상태에서 이슈 진행 선별 과정(Triage)를 통해 “CONFIRMED” 상태로 바꿉니다. 이 때 다음의 필드를 지정합니다.

• assignee: 이슈 진행 담당자

• planned version/s: 이슈를 진행하도록 계획된 버전

• priority: 이슈의 중요도에 따라 설정

• triage: “Confirmed” 상태로 넘어가는 경우 항상 “Approved” 설정

• labels: 필요한 레이블 자유롭게 설정

QA 메인테이너와 테스트 담당자는 “RESOLVED” 또는 "TEST" 상태인 이슈가 SPEC 변경이 필요하다고 판단하거나 QA 테스트를 통과하지 못하는 경우 “QA Not Satisfied” 버튼을 눌러 “CONFIRMED” 상태로 되돌릴 수 있습니다.

이슈 담당 개발자는 "ANALYSIS" 또는 "DEVELOP" 상태인 이슈를 다른 업무에 의해 더 이상 진행하지 못하는 경우에는 "stop work" 버튼을 눌러 "CONFIRMED" 상태로 되돌릴 수 있습니다.

새로운 개발 안건을 시작하거나 버그를 발견한 경우에 Jira 이슈를 생성합니다. 이슈 생성 절차 및 작성할 항목은 이슈 작성 절차에서 설명합니다. 이슈의 초기 상태는 “OPEN”으로 설정되지만, Triage를 통해 승인을 받기 위해서는 이슈 작성 완료 후 메인테이너에서 이슈를 "To Triage" 버튼을 눌러 프로젝트 메인테이너에게 전달해야 합니다.

이후 필요에 따라 각 상태로부터 다시 “OPEN” 상태로 되돌아갈 수 있습니다. 이슈 진행 중 어떤 상태 (CONFIRMED, ANALYSIS, DEVELOP, HANDOVER, RESOLVED)에서도 해당 이슈의 재확인이 필요한 경우 “Ask Reconfirmation” 버튼을 눌러 이슈의 상태를 “OPEN” 으로 되돌리면 자동으로 프로젝트 메인테이너에게 이슈가 할당됩니다. 또한, 완료된 (CLOSED) 이슈도 추후에 문제가 발생되면 “Reopen Bug” 버튼을 눌러 해당 이슈의 상태를 “OPEN” 으로 변경할 수 있습니다.

이슈 작성 절차

1. JIRA (jira.cubrid.org)에 로그인 후 상단의 오렌지색 “CREATE” 버튼을 클릭합니다.

2. 새로 열린 “CREATE Issue” 창에서 각 필드를 다음 표의 설명에 맞게 작성하고 하단의 “Create” 버튼을 클릭합니다.

Issue Types

Component

Component는 모듈 단위로 설정합니다. Component는 계층 구조로 구성되며 점점 세분화 됩니다. 이슈에서 다수의 Component를 선택할 수 있습니다. 위의 탭은 각 프로젝트 별 큐브리드 프로젝트에서 사용할 수 있는 Component입니다. 표에서 보는 것과 같이 CUBRID는 SM, QP, JavaSP, DS, Utility 등을 포함하고, 각 모듈 또한 다수의 모듈을 포함합니다.

이슈 생성 시, 해당 시점에 알 수 있는 연관 모듈을 선택합니다. 이슈를 분석하는 과정에서는 해당 이슈와 연관된 모듈 정보를 추가 선택할 수 있습니다. 예를 들어 SM 모듈에서 Buffer Manager를 개선하는 이슈인 경우, 이슈 생성 시 CUBRID, SM, Buffer를 선택할 수 있고, 이슈 진행 중에 File, Lock 모듈에 영향을 주는 경우 추가 선택할 수 있습니다.

CTE, TDE, JSON, Java SP등 여러 모듈에 영향을 주는 프로젝트인 경우 새로운 component를 생성하여 설정할 수 있습니다. 필요한 경우 프로젝트 메인테이너에게 요청하여 새로운 component를 생성할 수 있습니다.

이슈 내용 템플릿

템플릿은 이슈 타입에 따라 세가지 형태를 사용합니다.

Correct Error

• Description: 이슈 설명

• Repro: 버그를 재현하기 위한 절차를 입력합니다. 버그 재현에 대한 설명을 적기 보다는 환경 재현/스키마 생성/질의 실행/유틸리티 실행 등의 모든 절차를 복사-붙여넣기로 재현 가능하게 작성해야합니다. (재현을 위한 테스트 프로그램은 첨부해야 합니다.)

• Expected Result: 기대 결과 (고쳐져야 할 예상 결과)

• Actual Result: 현재 결과 (문제가 있는 결과)

• Additional Information: 추가로 버그 분석과 이해에 도움을 주기 위해 참고할 자료나 내용이 있다면 적어줍니다.

Improve Function/Performance, Development Subject, Refactoring

• Description: 이슈에 대한 설명을 적습니다.

• Specification Changes : 변경될 스펙을 정리하여 작성합니다. QA 테스트 정의, 매뉴얼 작성 등에서 활용할 수 있습니다.

• Implementation: 이슈를 해결하기 위해 디자인 명세, 구현 컨셉 및 상세를 작성합니다.

• Acceptance Criteria: 해당 이슈에 대해 요구사항에 따라 디자인과 구현을 수행하면서 선택하게 된 이슈의 범위 내에서 만족해야 하는 동작/결과를 정의합니다. 이 내용은 디자인/구현의 완료 판단(리뷰)의 기준이 됩니다. 만약 정의하지 않은 동작/결과가 크리티컬 하다면 디자인/구현에 대해 재검토할 필요가 있습니다.

• Definition of done: 이슈를 완료하기 위해 어떠한 방법으로 검증할 수 있을지를 작성합니다. 다음 예시와 같이 기입할 수 있습니다.

  • Acceptance Criteria를 만족시킨다.

  • QA 테스트를 통과한다.

Task, internal management

• Description: 작업 내용에 대한 목적과 설명을 적습니다.

Triage를 통해 지정된 개발자(assign에 의해 개발자가 변경 가능)는 “Start Analysis” 또는 "Start Develop" 버튼을 눌러 due date 정한 후 “ANALYSIS” 또는 "DEVELOP" 상태로 변경합니다. “ANANLSYS” 상태는 분석(디버깅 포함), POC, 설계 및 설계 리뷰 작업으로 구성되며, "DEVELOP" 상태는 구현, 유닛(unit) 테스트 및 동료 리뷰로 구성됩니다. 개발자는 진행 중인 개발 단계에 맞춰 개발 상태를 변경해야합니다.

개발자는 작업 진행 상태(ANALYSIS, DEVELOP)에서 “Need Analysis” 또는 "Need Develop" 버튼을 눌러 작업 진행 상태를 변경할 수 있습니다. 예를 들어 코드 리뷰를 진행하면서 발견한 문제를 간단한 수정을 통해 해결할 수 없고, 분석 또는 설계에서 고려가 더 필요한 경우 "Need Analysis" 버튼을 통해 "ANALYSIS" 상태로 변경합니다.

담당 개발자는 구현 완료 (동료 리뷰 및 코드 머지)된 후 "Accept the fix" 버튼을 통해 품질 보증팀(QA)에 이관에 필요한 작업을 하기 위한 "HANDOVER" 상태로 변경합니다. "HANDOVER" 상태에서는 매뉴얼 작성, 테스트 항목 작성 및 스펙 변경로 인해 수정이 필요한 regression 테스트 케이스를 수정합니다.

품질 보증팀 이관 후 QA 메인테이너 또는 테스트 담당자가 테스트 관련 추가 요청이 있을 경우 "Need Something" 버튼을 눌러 "HANDOVER" 상태로 변경할 수 있습니다.

담당 개발자는 작업 완료 (“HANDOEVR", "BACKPORT") 된 이후에 “Check-in Fix” 버튼을 눌러 “RESOLVED” 상태로 변경하고, 해당 이슈를 QA 메인테이너에 이관합니다. QA로 이관 후에는 이슈의 코멘트를 통해 개발자와 QA 담당자가 커뮤니케이션합니다.

“RESOLVED”로 상태 변경 시 다음의 필드를 필수로 입력해야 합니다.

• QA assignee: 변경 필요 없이 자동으로 할당됩니다. (기본 : QA 메인테이너)

• resolution: “Done”

• manual: 매뉴얼 작성 또는 수정이 필요한지 설정합니다. (need manual)

• QA scenario

  • not required : QA 시나리오 추가가 필요하지 않는 경우 (기본값)

  • required : QA 시나리오 추가가 필요한 경우

  • revise required : 기존 QA 시나리오의 변경이 필요한 경우

• fix version/s: 해당 이슈가 반영(merge)된 버전을 명시합니다. (이 필드는 QA팀에서 테스트 및 릴리즈를 위해 참조함)

QA 메인테이너는 QA 담당자를 지정해서 할당합니다. QA 담당자는 다른 작업에 의해 해당 이슈에 대해 더 이상 테스트할 수 없는 경우 "Stop Test" 버튼을 통해 "RESOVED" 상태로 변경할 수 있습니다.

프로젝트 메인테이너는 이슈 선별시("OPEN") 생성된 이슈가 버그가 아니라고 판단시 “Bug Invalid” 버튼을 눌러 “RESOLVED”상태로 변경할 수 있고, 담당 개발자는 이슈 진행 중 ("CONFIRMED", "ANALYSIS", 또는 "DEVELOP") 해당 이슈에 대하여 수정할 필요가 없다고 판단 시 “Resolve without fix” 버튼을 눌러 “RESOLVED” 상태로 변경할 수 있습니다. 이후에는 QA 메인테이너가 “CLOSED”상태로 변경하여 이슈를 종료하거나, 다시 버그로 판단해서 “OPEN”으로 변경할 수 있습니다.

QA 담당자는 해당 이슈에서 필요한 QA 작업이 완료되면 이슈를 종료하여 “CLOSED” 상태로 변경합니다. 이 때 다음의 사항을 확인합니다.

• QA scenario 추가/수정 및 통과 여부

• Planned version/s 에 따른 백포트 반영 여부

CUBRID에서는 소스 코드를 관리하고, 개발 진행 시 코드 리뷰와 같은 협업을 위한 도구로 Github을 사용하고 있습니다. Github을 기반으로 진행하는 개발 워크플로우를 잘 이해하기 위해서는 다음의 사항을 잘 이해하면 좋습니다.

• Git 사용법

• Git 브랜치 모델

• Pull Request와 자동화 도구

• 코드 리뷰

담당 테스터는 테스트 완료 후 "Need Backport" 눌러 planned version에 명시된 하위 버전에 백포트를 요청합니다. "BACKPORT"상태는 코드 및 테스트 케이스를 planned version에 명시된 develop 브랜치를 제외한 하위 브랜치에 백포트 작업을 진행합니다.

Git은 저장소와 관계없이 브랜치만을 기준으로 작업한다고 이해하면 쉽습니다. 따라서 큐브리드 메인저장소와 fork한 내 저장소 간에 sync를 맞추는 작업은 하지 않아도 됩니다. 개발을 진행하기 전 코드를 upstream으로부터 반영 할 브랜치를 가져와 작업을 시작하고, 결과물을 origin에 올리면 됩니다.

다음의 스크립트를 참고할 수 있습니다.

git remote add upstream https://github.com/CUBRID/cubrid.git

git remote -v
#====
#    origin  http://github.com/hgryoo/cubrid (fetch)
#    origin  http://github.com/hgryoo/cubrid (push)
#    upstream        http://github.com/cubrid/cubrid (fetch)
#    upstream        http://github.com/cubrid/cubrid (push)

git fetch upstream

# 작업할 새로운 브랜치 가져오기, upstream으로부터 브랜치 생성!
# git push로 잘못 반영되는 것을 방지하기 위해 
# 아래 두 명령어는 항상 함께 실행해야 합니다.
git checkout -b CBRD-55555_my_work upstream/develop
git push -u origin CBRD-55555_my_work

# 작업하기
git add ...
git commit …

# 소스를 올릴 remote 이름과 브랜치 이름을 항상 적어줍니다
git push origin CBRD-55555_my_work

# upstream의 develop의 내용을 반영하고 싶을 때
git fetch upstream
git merge upstream/develop

Git branch는 하나의 소프트웨어에 여러 개발자가 동시에 다양한 작업을 진행 할 수 있는 유용한 도구입니다. 각자 독립적인 영역에서 여러 용도로 사용할 수 있습니다. 자세한 내용은 링크를 참고합니다.

Github의 프로젝트들은 대부분 몇 가지 브랜치의 용도를 정해두고 운영하고 있습니다. 예를 들어 develop 브랜치는 최신 개발 사항을 계속 담고, master 브랜치는 안정화 된 버전을 관리하는 것입니다. 각 브랜치의 용도를 정하는 방식으로 활용하여 오픈소스 프로젝트를 운영하는 여러 가지 방법들이 있습니다. 그 중 CUBRID는 많은 오픈소스 프로젝트에서 도입하는 Vincent Drissen 브랜치 모델을 기반으로 운영하고 있습니다.

CUBRID의 브랜치 모델과 VD 모델의 차이

Vincent Drissen 모델(이하 VD 모델)에서는 영구적으로 유지되는 develop, master 브랜치와 임시 브랜치인 release, feature, hotfix 가 존재합니다. VD 모델과의 차이점은 CUBRID에서는 이전 버전의 릴리즈도 유지보수 하고 있기 때문에 이전 버전의 릴리즈 브랜치도 영구적으로 유지합니다. (e.g. release/10.2, release/11.0) 예를 들어 develop 브랜치에서 최신 버전인 11.4 버전을 개발하고 있더라도, release/10.2라는 브랜치도 10.2.2, 10.2.3 마이너 버전 릴리즈를 위해 계속 유지합니다.

VD 모델에서 최신 버전 릴리즈 과정에서 임시적으로 생성하는 release 브랜치와 동일한 역할을 하는 pre-release 브랜치를 생성합니다. 자세한 설명은 Release 섹션을 참조합니다.

하나의 Pull Request로 개발을 완료하기 힘든 프로젝트의 경우 피쳐 브랜치를 활용할 수 있습니다. 피쳐 브랜치에 대한 설명은 다음 별도의 섹션에서 기술합니다.

QA 담당자는 "Start Test" 버튼을 눌러 "TEST" 상태로 변경합니다. "TEST" 상태는 매뉴얼 테스트, 테스트 시나리오 작성 및 테스트 성공 여부를 확인합니다.

프로젝트 메인테이너, QA 메인테이너 및 QA 담당자는 종료된 이슈("CLOSED")에 대해 추가적인 테스트가 필요시 "Need Test"를 통해 "TEST"로 상태를 변경할 수 있습니다.

backport란 새로운 버전의 기능 및 수정사항을 이전 버전에 반영하는 것입니다. 예를 들어 CUBRID 11에서 발견되어 고쳐진 버그를 CUBRID 10.2.1 버전에서도 발생하여 마찬가지로 고쳐야 하는 경우 backport를 진행합니다.

이 경우 Github 도구의 관점에서 보면 develop 브랜치에 반영된 커밋을 release/10.2 브랜치에 반영하는 것입니다. 이 때 주의할 사항은 여러 버전에 반영해야 하는 기능이나 버그 수정의 경우 반드시 develop에 먼저 커밋을 반영하고 release에 backport 해야 합니다. QA regression 결과 확인 및 추가 패치를 통해 검증된 패치를 이전 버전에 backport 할 수 있기 때문에 이전 버전의 안정성을 해치는 것을 최소화 할 수 있습니다. 만약 develop에서 발생하지 않는 경우 release에만 반영합니다.

backport 시 다음을 참고하여 진행합니다.

• 여러 버전에 한꺼번에 반영할 때는 develop 브랜치에 우선 반영해야 합니다.

• develop에서 먼저 반영한 commit이 안정적인지 확인합니다.

• git cherry-pick을 활용하면 대부분의 경우 쉽게 backport 할 수 있습니다.

#git 명령어 예시 
git checkout develop
git log // backport 할 commit id 찾기
git checkout release/10.2
git cherry-pick <commit-id>

• conflict 발생 시에는 수정 후 PR을 생성합니다.

• backport 과정에서 버그가 발생하는 경우 수정하고, 관련 내용을 JIRA에 기록합니다.

backport PR 생성 시 다음을 참고합니다.

• PR 생성 시 PR 제목 마지막에 develop에 반영된 PR의 번호를 함께 기록합니다.

  • 예시) [CBRD-OOOOO] Fix this issue: develop에 반영하는 PR, #235 [CBRD-OOOOO] Fix this issue (#235) : release/10.2에 반영하는 PR

• PR 내용에도 다음과 같이 원본 PR의 번호를 기록합니다. backport 뒤의 PR 번호는 자동적으로 github에서 링크로 만들어주는 것을 볼 수 있습니다.

backport 시 JIRA에 업데이트해야 할 내용은 다음을 참고합니다.

• QA 이관 전

  • Planned Version(s) 중 최신버전 (develop) 과 backport 대상 버전에 대해 모두 PR 생성

  • 각 PR에 대해 코드 리뷰 후 머지 완료

  • 개발자는 해당 JIRA 이슈에 PR 반영된 버전을 Fixed version(s) 기록

• QA 이관

  • “Resolved” 상태로 바꾸기

• QA는 테스트 완료 후 이슈를 “Close” 상태로 변경

새로운 기능 개발 및 버그 수정이 필요할 때에 'develop' 브랜치로부터 분기하여 feature 브랜치를 만들수 있습니다. 이 브랜치는 fork한 내 저장소에서 ‘develop’ 브랜치로부터 분기한 브랜치와는 다릅니다.

Feature Branch의 이름은 다음과 같이 작성합니다.

• feature/<이름>

예시) feature/javasp, feature/tde, feature/truncate_table

• 위와 같은 이름으로 설정하면, 자동으로 Github check이 수행될 수 있습니다.

이 브랜치의 주요 목적은 반영할 코드의 규모가 클 때 코드 리뷰를 여러 라운드에 나누어 진행하기 위한 목적입니다. ‘develop’에 개발 할 기능의 일부만을 바로 반영하지 않고 feature 브랜치에서 여러 개의 PR로 효율적인 코드 리뷰와 검증 과정을 거친 후 좀 더 안정적으로 ‘develop’에 반영합니다.

git 명령어는 다음과 같이 참고하여 관리합니다.

# 1. feature 브랜치 생성
git remote add upstream 
http://github.com/cubrid/cubrid

git fetch upstream
git checkout -b feature/my_feature upstream/develop
git push -u upstream feature/my_feature

# 2. github에서 여러 번의 PR
git fetch upstream
git checkout -b CBRD-OOOOO upstream/feature/my_feature
   # many commits (개발 진행)
git push -u origin CBRD-OOOOO
   # PR 생성 후 코드 리뷰
# 2. 를 여러 번 반복 == 여러 번의 리뷰 라운드

# 3. develop과 sync by merge (sync를 위한 커밋은 PR하지 않음)
git checkout feature/my_feature
git fetch upstream
git merge upstream/feature/my_feature // should be fast-forward merging
git merge upstream/develop
git push upstream feature/my_feature

# 2. 를 여러 번 반복 == 여러 번의 리뷰 라운드

git push origin CBRD-OOOOO

# CBRD-00000에 대한 PR 생성

참고! Feature Branch는 임의로 생성할 수 있으며, 기능의 리뷰를 완료하고 develop 브랜치에 머지한 경우 삭제합니다.

개발 중이나 개발 완료 후 매뉴얼 추가/수정이 필요한 경우 상단의 가이드라인과 동일한 방식으로 매뉴얼 JIRA 와 매뉴얼 Github에서 수행합니다.

• 매뉴얼 JIRA: http://jira.cubrid.org/projects/CUBRIDMAN

• 매뉴얼 Github: https://github.com/CUBRID/cubrid-manual

구체적으로 다음의 절차를 따릅니다.

• 매뉴얼 JIRA 이슈 작성

• 만들어진 매뉴얼 JIRA를 CBRD나 APIS 프로젝트의 이슈와 연결

• 매뉴얼 작성 후 Pull Request 생성

• 매뉴얼 리뷰와 코드 머지 (이전 버전 포함)

• 매뉴얼 JIRA의 상태를 “Done”으로 변경

Pull Request 내용 구성

Pull Request의 제목에는 항상 관련된 JIRA 이슈 번호를 기입해야 합니다. 그러나 이슈 번호 외에 JIRA의 제목 PR의 제목이 동일할 필요는 없습니다. Pull Request의 내용을 가장 잘 설명할 수 있는 제목이면 좋습니다.

Pull Request의 설명 첫 줄에는 항상 관련된 JIRA의 링크를 첨부해야 합니다. 코드 리뷰를 위해 JIRA에서 설계에 관련한 내용을 참조하기 위함입니다. 또한, 이슈나 설계 문서에서 담지 못한 구현 디테일 (클래스, 함수, 특정 로직) 의 목적, 구현, 참고사항 등을 작성하면 이후 코드 분석에 도움이 됩니다.

• Purpose: PR에서 반영하려는 코드의 설명, 목적을 간단하게 기술합니다.

• Implementation: JIRA 이슈나 설계서에 작성된 설계 외에 반영할 코드와 관련하여 구현하는 로직, 클래스, 함수 등의 설명을 자세히 설명할 필요가 있다면 기술합니다.

• Remarks: 나머지 참고 사항을 적습니다.

Pull Request의 우측에는 assignees, reviewers, labels, projects, milestone을 설정할 수 있습니다. Pull Request 생성 시 assignees만 입력하고 나머지 필드는 사용하지 않습니다. reviewers는 코드 리뷰를 진행하기 전에 등록합니다. 다음의 코드 리뷰 섹션을 참조합니다.

코드 리뷰

코드 리뷰를 지정/요청하기 전 리뷰어에게 설계 디자인 리뷰를 완료해야 합니다. 코드 만으로는 변경의 의도와 내용을 명확히 파악하기 힘들기 때문입니다. 따라서 디자인 문서 (Concept, Architecture) 를 프로젝트 구성원에게 코드 리뷰 이전에 공유해야 합니다.

• JIRA에 디자인 문서를 공유

• 문서의 형식은 자유

• 리뷰어가 설계 디자인에서 더 이해가 필요한 경우 자료 요청 가능

설계 디자인 리뷰를 완료하면, 코드 리뷰를 진행합니다. PR 우측의 Reviewers를 설정하여 코드 리뷰를 시작합니다.

다음과 같은 변경이 크지 않은 간단한 버그 수정이나 기능 구현은 설계 디자인 리뷰와 코드 리뷰를 동시에 진행하는 것도 괜찮습니다.

• 스펙 변경이 없음

• 기능 동작의 변경이 없음

• 규모가 크지 않은 리팩토링

자동화 도구 (CI)

효과적/효율적인 코드 리뷰를 위해 Github PR에 여러 자동화 도구들을 도입하고 있습니다. 이 도구들은 코드의 품질을 높이고 리뷰어가 단순 실수가 아닌 설계 디자인과 로직 문제에 집중할 수 있도록 도와줍니다.

• license: 올바른 형태의 라이센스 헤더 주석을 가지고 있는지 확인합니다. 문제가 있다면 실패하고, 어떤 파일을 확인하다 문제가 발견되었는지는 Details를 통해 확인할 수 있습니다.

• pr-style: 모든 Pull Request (PR)들이 각각의 JIRA 이슈와 연결되어야한다는 규칙을 가지고 있고, 이 이슈 번호가 PR 제목의 앞부분에 명시되어야 합니다. pr-style은 이를 확인하고 규칙을 어겼다면 실패합니다.

• code-style: 일관성 있는 코드 유지를 위해 정의된 코드스타일을 따르는지 확인합니다. 코드 스타일은 코드 포맷팅 도구들을 이용하여 정의 되며, code-style은 이 도구들을 이용해 정해진 규칙을 올바르게 따르는지 확인하고 수정합니다. 만약 규칙과 다르다면 실패하고 PR의 suggestion을 통해 리포트 합니다. 지원하는 언어와 코드 포맷팅 도구를 다음과 같습니다.

  • C: GNU Indent 2.2.11

  • C++: astyle 3.1

  • Java: google java format 1.7

• cppcheck: 사용되지 않는 변수, NULL 참조 등 개발자가 저지를 수 있는 많은 문제들이 정적 분석을 통해 발견될 수 있습니다. 이러한 오류들은 실수하기 쉽지만 명백하여 문맥없이 코드를 살펴보는 것만으로 찾아낼 수 있습니다. 그렇기에 리뷰어가 일일이 찾아내고 코멘트를 다는 것은 낭비입니다. cppcheck은 이러한 문제들을 잡아냅니다. 에러가 있을 경우 실패하고 PR에 코멘트를 사용하여 리포트 합니다. 이 때 리포트는 에러와 경고의 갯수입니다. 자세한 내용은 Details 를 통해 확인할 수 있습니다. 만약 에러는 없고 경고만 있다면 테스트는 통과합니다.

• coverage: 코드 커버리지를 확인하고, 수치가 떨어진 경우 codecov 서비스로 알려줍니다.

• Build Tests: PR이 적용된 후에도 각종 환경에서 올바르게 빌드가 수행되는지 확인합니다.

  • appveyor/pr: Windows

  • travis-ci/pr: Ubuntu

  • circleci: build: CentOS 7

• Regression Tests: 소스를 빌드하고 실제로 여러 SQL 구문을 수행하여 데이터베이스의 기능들이 올바르게 동작하는지 확인합니다. 이는 QA Home에서 확인할 수 있는 수많은 테스트의 일부이며, 변경사항이 develop에 반영되기 위한 최소한의 충족요건입니다. CUBRID/cubrid-testcases 저장소에서 테스트들을 확인할 수 있습니다.

  • circleci: test_sql: 새로운 데이터베이스를 생성하여 각종 sql 문들을 수행하고 기대한 결과가 나오는지 확인합니다.

  • cicleci: test_medium: 이미 많은 테이블들과 데이터들이 생성되어 있는 데이터베이스에서 각종 sql 문들을 수행하고 기대한 결과가 나오는지 확인합니다.

브랜치 별 자동화 도구 수행

• Build Tests와 Regression Tests는 저장소 내의 모든 브랜치에서 동작합니다.

• 나머지 도구들은 develop, feature/* 및 일부 릴리즈 브랜치 (현재 release/11.*)에서만 동작합니다. 특히 feature 브랜치의 경우 이름 규칙을 적용해야 github check가 올바르게 작동합니다.

코드 머지 전 자동화 도구에서 실패 시 가이드라인

자동화 도구에서 통과되지 않아 반영 버튼이 비활성화 되어 있는 경우, CUBRID 프로젝트 메인테이너와 논의 후 메인테이너가 직접 반영해야 합니다. 이 경우, 자동화 도구에 문제가 있다고 판단되거나, 자동화 도구에서 보고된 문제를 무시해도 된다는 합의를 거친 것입니다. 이러한 정책의 이유는 다음과 같습니다. 자동화 도구에서 검사하는 것은 기존의 동작의 변경되었는지를 확인합니다. PR의 코드 변경이 개발자의 의도와 상관 없이 스펙 변경이 발생했을 수도 있습니다. 이 경우 프로젝트 메인테이너에게 머지 요청을 하면서 자동화 도구에서 실패한 사항에 대해서 커뮤니케이션과 검토 과정을 거쳐야 합니다.

코드 머지 전 검증

코드 머지 전 PR의 자동화 도구에 포함되지 않는 테스트를 미리 검증하기 위해 QA 팀에 빌드된 파일을 전달하여 수동 검증을 요청할 수 있습니다. 다음의 절차로 진행합니다.

• 빌드 후 설치 파일을 QA 팀에 이관합니다.

• 테스트는 수동으로 진행하기 때문에 시간이 소요될 수 있습니다.

• 테스트가 완료되면 QA Home 페이지 왼쪽 탭의 RB-<version>-Manual에서 테스트한 버전의 결과 리포트를 확인 할 수 있습니다.

다음의 경우 이 검증을 활용하는 것을 권장합니다.

• 검증해야 하는 테스트 케이스 또는 상황을 특정할 수 있는 경우

• QA의 테스트 케이스가 복합적으로 돌아야 발생하는 버그

  • 예를 들어 하나의 SQL과 간단한 디버깅으로 버그를 찾기 힘든 경우, 확인을 위한 디버깅 로그를 코드에 넣어두고 QA 시스템 환경에서 여러 테스트가 돌도록 하여 복잡한 경우를 확인하는 용도로 사용하면 좋습니다.

• QA 자원의 무분별한 소모를 막기 위해 TDD의 용도로 이 절차를 활용하지 않도록 합니다.

코드 머지

코드 리뷰를 통과하지 않고 코드를 머지할 수 없습니다. 자동화 도구에서 검증되었고, 리뷰어가 모두 “Approved” 한 경우에 머지할 수 있습니다. 이 경우 “Squash and Merge” 버튼이 활성화 되고, 저장소에 반영하는 커밋을 생성할 수 있습니다.

코드 머지 (Squash and Merge) 시 다음의 포맷으로 메시지를 작성해야 합니다.

• Title

  • [이슈 번호] 작성

  • PR의 제목과 동일해야합니다

• Message

  • 첫 줄에는 PR과 동일하게 JIRA 이슈의 경로를 작성합니다.

  • 둘째 줄은 비워둡니다.

  • 셋째 줄부터 반영하는 commit에 대한 설명을 작성합니다.

예시)

참고로 코드 머지 후 QA 시스템에 크게 영향을 주는 경우 QA 팀에서 해당 머지된 commit을 revert 할 수 있습니다. 자세한 내용은 Workflow after code merging의 테스트 실패 (regression) 발생 시 절차 가이드를 참고합니다.

만약 누군가 큐브리드에 처음 기여를 하는 경우 Pull Request를 통해 코드를 반영하기 전에 CLA를 제출하였는지 확인해야 합니다. 다음의 링크를 참고합니다.

QA 팀에서 테스트 시스템을 운영하기 위해 Jenkins라는 CI 툴을 운영합니다. Pull Request가 반영되면 (merge), Jenkins는 Github과 연결되어 있어 반영된 사항을 자동으로 테스트를 진행합니다. (참고: )

Jenkins에서 테스트가 모두 수행되고 그 결과 리포트는 에서 확인할 수 있습니다. 페이지의 좌측에서 버전별 테스트 결과 리포트를 확인할 수 있고, 오른쪽에는 최신 테스트 리포트에 대한 요약을 보여줍니다.

좌측에 테스트 결과 리포트를 눌러보면 아래의 그림과 같은 탭이 있습니다. 각각 기능, 성능, 메모리 누수를 테스트한 결과를 보여줍니다. (제일 우측의 버튼은 개발팀에서 사용하지 않습니다)

테스트는 기능적 테스트 (Function Test)와 비기능적 테스트 (Non-Function Test)로 나누어져 있습니다. 먼저 기능 테스트를 살펴보면, 리눅스와 윈도우 환경에 대해 각각 테스트를 진행하고 있습니다. 현재 윈도우는 리눅스보다 테스트하는 항목의 개수가 적습니다.

큐브리드에서 기여는 다음의 활동을 통해 진행합니다.

• 사전 커뮤니케이션: 기여자가 어떤 버그나 개선할 사항을 찾는 경우 프로젝트 메인테이너와 커뮤니티에 의견과 방법을 제안

• 이슈 생성: 사전 커뮤니케이션을 통해 기여 내용과 방향에 대한 의견이 충분히 수렴되었고 기여하기 위한 합의에 도달했다면 이슈를 생성

• Pull Request 생성: 이슈 해결의 산출물, 설계 디자인과 코드 리뷰 수행

외부 기여를 받을 때 가장 중요한 목표는 외부 기여자의 활동을 끝까지 마치도록 유도하는 것입니다. 그 중 기여의 시작인 커뮤니케이션이 가장 어렵고 귀찮은 단계입니다. 프로젝트 메인테이너에게 설득을 위해 테스트 자료, 간단한 설계 디자인, 코드 분석 등이 선행되어야 하기 때문입니다. 또 지금 큐브리드에 어떤 기능 개선이 필요한 지 직접 찾아내는 것도 쉽지 않습니다.

프로젝트 메인테이너와 코어 개발자가 어떤 기능에 대해 이미 진행을 합의했지만 리소스 부족으로 진행하지 못한 경우 이슈를 미리 만들어 두기도 합니다. 이러한 이슈를 활용하면 커뮤니케이션과 이슈 생성 단계를 생략하고 외부 기여자가 쉽게 시작해볼 수 있습니다.

특히 미리 만들어둔 이슈 중 비교적 기여 난이도가 쉽고 짧은 시간에 기여해볼 수 있는 이슈에 대해 “Good First Issue” 이슈로 설정해두고 가이드한다면 기여자가 좀 더 쉽게 큐브리드에 기여를 시작할 수 있습니다. 한 번 기여 프로세스를 경험하고 나면 그 다음엔 훨씬 쉽게 기여할 수 있을 것입니다.

“Good First Issue”는 JIRA Issue label에 지정해두고 커스텀 필터로 만들어두고 가이드하면 좋습니다.

큐브리드의 기여자를 위한 커뮤니케이션 채널로 Reddit (영문)과 큐브리드 Q&A 게시판 (국문)이 있습니다. 큐브리드 Q&A는 대부분 일반 사용자를 중심으로 버그 리포트와 질문 위주로 사용하고 있습니다.

그 외에 이메일, Stack Overflow 등의 수 많은 커뮤니케이션 채널으로 기여에 대한 질문이나 제안을 받을 수 있지만 공식적인 커뮤니케이션 채널 (cubrid.com 또는 reddit)에서 유도하여 이어가는 것이 중요합니다.

만약 QA팀에서 테스트 도구에서 검증 후 반영한 변경에 문제가 있어 QA 시스템에 크게 영향을 주는 경우 QA팀에서 해당 변경의 commit에 대해 revert 하고 JIRA를 “CONFIRMED” 상태로 되돌릴 수 있습니다. 이 때 개발자가 해당 이슈가 다시 triage가 필요하다고 판단하는 경우 “OPEN” 상태로 되돌릴 수 있습니다.

QA 시스템에 영향을 주는 경우는 다음의 예시와 같은 문제를 즉시 해결하지 못하는 경우입니다.

• 일부 또는 전체 시스템이 종료되는 경우 (core 파일 생성)

• 시스템이 멈추는 경우 (hang)

• 이슈와 디자인 문서에서 정의한 동작과 다른 경우

• 너무 많은 테스트 케이스 실패가 발생하는 경우

• 심각한 성능 저하가 발생하는 경우

위의 상황이 지속된 상태로 QA 시스템이 계속 운영되는 경우, 이를 기반으로 다른 기능을 개발할 때 결과의 신뢰성(robustness)에 영향이 있고 이후 문제 파악에 필요한 비용이 기하급수적으로 커지게 됩니다.

만약 JIRA가 “OPEN” 상태로 돌아간다면, JIRA Workflow에 따라 설계 디자인과 구현, 코드 리뷰 단계를 처음으로 다시 진행하는 것과 같습니다. 각 단계에서 재검토가 필요하다면, 피쳐 브랜치를 생성하여 진행하는 것을 권장합니다.

이 섹션은 개발 가이드라인 범위는 벗어나있지만 참고할만한 내용이기 때문에 모든 절차가 자세히 기술되진 않았습니다. 버전 정보와 릴리즈를 위한 개략적인 절차를 참고로만 읽어주세요.

Version

Build Number

큐브리드의 빌드 번호는 다음과 같은 규칙을 가집니다.

• Major.Minor.Patch.Revision

  • e.g) 11.1.0.0512.2d9a03248

  • Patch는 이전 릴리즈 시점부터 commit count를 기준으로 증가합니다.

  • Revision은 빌드 시점의 commit hash가 입력됩니다.

Code Name

Major와 Minor 버전 릴리즈 시 다음의 예시와 같이 코드 네임을 가집니다.

• 과일 이름

  • elderberry (11.1)

  • damson (11.0)

  • cherry (10.2), cherry sherbet

  • banana (10.0), banana pie (10.1)

• 버전 번호는 항상 바뀔 수 있습니다.

• 릴리즈 후에는 코드 네임 대신 버전 번호로 관리합니다.

Release milestones

Major 버전 릴리즈 시에 다음과 같은 마일스톤을 가집니다.

• Code Freeze

  • CC (Code Complete): All major changes are completed

  • ZAB (Zero Active Bug): All triaged issues are resolved

• ZRB (Zero Resolved Bug): All resolved issues are closed

• FTC (Full Test Complete): Full tests for release are succeed

  • GA (General Availability build): Distribute the release version

릴리즈 절차

• Code Freeze 후 develop로부터 pre-release 브랜치를 생성하여 관리합니다.

• ZRB 달성을 위해 pre-release 브랜치에 major change에 대한 regression 패치를 합니다.

• ZRB에서 release를 위한 full test를 진행합니다.

• FTC에서 release를 위한 테스트로부터 regression 해결을 위해 pre-release 브랜치에 적용한 major change에 대한 패치를 develop으로 port 합니다.

• FTC 이전에 패치가 충분히 검증 되었다면 미리 develop으로 port 할 수 있습니다.

• GA 시 pre-release는 release로 만들고 제거합니다.

최신 메이저 버전이 아닌 이전 버전의 릴리즈와 핫픽스의 경우 pre-release 브랜치를 생성하지 않고, develop으로부터 backport 후 full test를 진행하고 릴리즈합니다.