TWTL Doc 002
개발 프로젝트 진행에 필요한 분야별 역할에 대해 간단히 소개하며, 각 분야별로 구성된 Git 저장소(repository)의 목록을 제시합니다. 저장소의 용법에 대해 설명하고 Git 형상 관리 규약에 대해 논의합니다.
TWTL 프로젝트의 저장소는 다음과 같습니다.
전체 빌드, 테스트, 문서와의 통합 및 패키징을 위한 모듈 저장소입니다.
본 문서를 포함, 프로젝트 전체 진행에 있어 필요한 모든 문서를 작성하는 저장소입니다. TWTL Doc 001과 후속 문서에서 기술합니다.
보안 솔루션 소프트웨어 TWTL의 본체를 이룰 두 부분인 엔진과 GUI, 그리고 Service의 소스 코드 개발을 세 저장소에서 나누어 각각 구성합니다. 엔진과 GUI, Service에 대해서는 TWTL Doc 006에서 기술합니다.
주로 엔진의 기능이나 엔진-GUI 연결의 안정성 등을 테스트하기 위해 작성되는 코드입니다. 테스트에 대해서는 추후 문서에서 기술합니다.
Git은 버전 제어를 포함한 형상 관리 도구입니다. 개인 프로젝트의 경우 기억에 의존해 적절히 관리해도 됩니다. 하지만 공용 저장소에서는 이렇게 할 수 없기 때문에 여러 면에서 형상 관리가 정상적으로 작동하기 위한 규약을 정하는 것이 중요합니다.
TWTL 프로젝트의 Git 컨벤션은 Git이나 그 외의 도구를 활용하는 여러 다른 프로젝트에서 쓰이고 있는 방식 중 일부를 가져온 것입니다. 따라서 이들 규약은 경험적으로 검증되어 있으며 형상관리에 있어 소통을 저해하는 요소나 실수를 줄여 줍니다. 그러나 역시 중요하여 무시할 수 없는 것은 역시 연습과 경험에 의한 숙달이고, 버전 제어 및 형상 관리에 대한 지식입니다. 규약에 기대지 말고 꾸준히 배우며, 때로는 규약을 개선할 점이 있다면 그렇게 하도록 합시다.
커밋 메시지는 영어로 작성합니다. 가능하다면 라틴 알파벳과 숫자 등 GL 내의 문자로만 이루어져 있도록 합니다. 또한 50자 이내로 쓰는 것이 권장되며 첫 줄이 70자를 넘기지는 않도록 합니다. 이는 대부분의 환경에서 커밋 메시지가 정상적으로 보이도록 함입니다.
커밋 메시지에 가장 공통적으로 등장할 수밖에 없는 내용은 "나는 ~ 했다"입니다. I added, I wrote, I modified, I deleted, I merged, I patched, …. 이렇게 쓰지 않습니다. 문장일 경우 주어를 생략하고 술어구의 주동사 원형을 밝혀 원형부정형(root infinitive)으로 적습니다. Add, Wrote, Modify, Delete, Merge, Patch, …. Merge ~의 경우 git의 merge 명령어에 따른 자동 커밋 메시지에서도 쓰이는 형태입니다.
명사구를 커밋 메시지로 적는 것 역시 허용되며 이 경우 동사를 현재분사형(present participle) 또는 과거분사형(past participle)으로 활용해 적으면 좋습니다. 물론 to/for/of 등으로 이루어진 형용구(adjective clause)도 좋습니다. 명사구로 이루어진 커밋 메시지는 대표적으로 Multiple changes:가 있습니다.
커밋 메시지는 여러 줄로 작성될 수 있으며 이 때 첫 줄을 요약(summary)라고 부릅니다. Multiple changes의 경우, 첫 줄 이후 커밋 메시지에 여러 변경 중 각 사항에 대해 서술하는 항목으로 이루어진 리스트를 작성할 수 있습니다.
커밋 메시지 내에 등장하는 코드 조각은 `로 감쌀 수 있습니다.
상호 연관이 적은 부분들로 구성된 저장소의 경우, 위와 같은 형식으로 쓰인 커밋 메시지 앞에 부분에 해당하는 이름을 쓰도록 합니다. Documentation 저장소의 경우 각 문서에 해당하는 여러 폴더로 나뉘어 있기 때문에, Add README 메시지를 000-template 부분에 대해 적용할 경우 Add README in 000-template라고 하기 보다 000-template: Add README라고 하는 것이 낫습니다.
master 브랜치에서 작업하지 않습니다.
현재의 TWTL 프로젝트와 같이 소규모로 개인에 따라 여러 기능을 나눠 맡는 경우, 가장 권장되는 방식은 개인 ID로 된 브랜치에서 작업하는 것입니다. 개인 ID와 같은 브랜치가 여럿 필요한 경우, ID-feature-기능이름 꼴로 된 브랜치 이름을 여럿 두고, 이를 ID 브랜치에 merge할 수 있습니다.
한편 여러 사람이 한 기능에 대해 작업하고 있거나, 많은 사람이 볼 것을 가정한다면 feature-기능이름 꼴로 된 브랜치에서 작업하면 됩니다. 이 때 필요하다면 각 개인은 feature-기능이름-ID 꼴로 된 브랜치에서 작업한 후 주 기능 브랜치에 merge할 수 있습니다.
- Documentation 저장소의 경우 현재 담당자가 3명입니다. 로컬에서 Git 저장소를 관리하는 비용을 줄이기 위해 일단 GitHub에서 Markdown 에디터를 이용해 작업하고 있습니다. 이 때문에 master 브랜치에서 작업하는 것이 거의 불가피하며 더욱 신중한 작업이 요구됩니다.
- GUI 저장소의 경우 현재 담당자가 1명입니다.
- Engine 저장소의 경우 현재 담당자가 2명이며, 단일 대상에 대한 개발이며 형상 관리 도구의 활용 이상의 빠른 소통에 의존한 개발이 진행되고 있기 때문에 모델은 쓰일 수도 안 쓰일 수도 있습니다.
- TestSuite 저장소의 경우 현재 담당자가 2명이며 이 저장소가 정확히 위에서 설명한 경우와 부합합니다.
이처럼 항상 모든 작업에서 최소 1개 이상의 브랜치를 잡고 작업하는 경우, master 브랜치로부터 변경을 가져오기 위해, 또 master 브랜치로 변경을 반영하기 위해 merge(또는 cherry-pick이나 patch 등)가 필요하게 됩니다. 이 때 중요한 것은 각각의 브랜치가 중심을 잡는 것으로, 한 브랜치가 다른 브랜치에 달라붙어 버리지 않아야 합니다. (그렇게 되는 경우 브랜치 고유의 변경에 대해 나중에 추적하기 힘들게 됩니다.) 따라서 merge를 하되, --no-ff 옵션을 잊지 않도록 합니다.
서브모듈은 Build 저장소에서 가장 적극적으로 쓸 기능이며, 다른 저장소에서는 쓰지 않게 될지도 모릅니다.
빌드, 테스트, 문서 통합, 패키징을 위해 별도의 저장소를 쓰는 것은 실험적인 선택이었고, 프로젝트 초기에 이를 별도의 저장소로 구성하는 대신 브랜치를 나눠서 처리하자는 의견이 있었습니다. 그러나 Git submodule을 로컬에서 빌드용으로 무난하게 쓰기 위해서는, submodule의 대상 저장소를 자기 자신으로 (url = . 또는 url = ./) 지정할 수 있어야 합니다. 후자는 오늘날 사용 가능하나, 이 방식은 Git의 과거 버전에서 지원되지 않으며 여러 구현체에서 작동하지 않는 등 혼란을 초래합니다.
서브모듈의 URL은 GitHub 저장소 주소(.git 포함 https 주소)를 기준으로 합니다.