큐브리드는 를 사용하여 프로젝트를 관리하며 모든 변경사항은 이슈를 단위로 하여 관리 합니다. 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" 상태는 하위 버전에 테스트 완료된 이슈의 코드 및 매뉴얼을 반영합니다.

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

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

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

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

담당 개발자는 작업 완료 (“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 시나리오 추가가 필요한 경우

• 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”으로 변경할 수 있습니다.

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

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

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

• Git 브랜치 모델

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

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

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

프로젝트 메인테이너는 “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" 상태로 되돌릴 수 있습니다.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• https://www.cubrid.org/contributor_agreement

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

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

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

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

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

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

• 매뉴얼 JIRA 이슈 작성

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

• 매뉴얼 작성 후 Pull Request 생성

문서 이력

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Version

새로운 개발 안건을 시작하거나 버그를 발견한 경우에 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: 이슈 설명

• Test Build: Repro, Actual Result와 동일한 현상을 보여주는 빌드 버전을 commit 번호까지 상세히 기입합니다. 예를 들어 다음과 같이 기입할 수 있습니다: CUBRID-11.0.0.0248-b53ae4a JIRA 필드의 Affected version/s은 Major와 Minor 버전까지만 표시하는 반면, Patch와 Revision을 포함하여 실제로 버그가 발생한 구체적인 버전 명을 입력해야합니다. 버전명의 규칙은 섹션을 참고합니다. 빌드한 OS의 버전도 함께 명시할 수 있습니다.

예시)

Improve Function/Performance, Development Subject, Refactoring

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

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

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

예시)

Task, internal management

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

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 브랜치를 생성합니다. 자세한 설명은 을 참조합니다.

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

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

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

• feature/<이름>

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

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을 통해 리포트 합니다. 지원하는 언어와 코드 포맷팅 도구를 다음과 같습니다.

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

  • appveyor/pr: Windows

  • travis-ci/pr: Ubuntu

브랜치 별 자동화 도구 수행

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

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

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

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

코드 머지 전 검증

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

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

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

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

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

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

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

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

코드 머지

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

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

• Title

  • [이슈 번호] 작성

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

예시)

참고로 코드 머지 후 QA 시스템에 크게 영향을 주는 경우 QA 팀에서 해당 머지된 commit을 revert 할 수 있습니다. 자세한 내용은 Workflow after code merging의 를 참고합니다.

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

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