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

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

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

프로젝트 메인테이너는 “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라는 하나의 큰 프로젝트에 함께 기여하고 있습니다.

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

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

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

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

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

• Issue Tracking: JIRA ()

• Code Repository and Code Review: Github ()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Git 사용법

• Git 브랜치 모델

• Pull Request와 자동화 도구

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• feature/<이름>

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

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

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

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

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

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 할 수 있습니다.

• 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에 대해 코드 리뷰 후 머지 완료

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

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

Version

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

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

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

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

새로운 개발 안건을 시작하거나 버그를 발견한 경우에 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: 작업 내용에 대한 목적과 설명을 적습니다.

Pull Request 내용 구성

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

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

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

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

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

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

• 매뉴얼 JIRA 이슈 작성

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

• 매뉴얼 작성 후 Pull Request 생성