GitLab에는 전담 "소프트웨어 아키텍트"가 없습니다. 모두가 각자 결정을 내리고 그 결정을 적절히 문서화하도록 권장합니다. 이러한 결정을 어디에 어떻게 문서화하는지는 아래에서 설명합니다.

결정 사항 문서화#

새 기능을 만들 때는 만들려는 대상의 범위와 규모를 먼저 가늠합니다. 그 답에 따라 작업을 뒷받침할 수 있는 도구나 프로세스가 여러 가지 있습니다. GitLab은 기능 개발 과정을 가능한 한 효율적으로 유지하는 것을 지향합니다. 일반적으로는 시간이 더 많이 드는 방식의 추가 지원과 구조가 필요하지 않다면 가장 단순한 프로세스를 사용합니다.

머지 리퀘스트#

변경의 영향이 그룹 안에 한정되거나 기여자가 한 명뿐이라면, 아키텍처 결정을 문서화하는 가장 작은 단위는 커밋이며 나아가 머지 리퀘스트(MR)입니다. MR과 커밋은 머지된 뒤에도 참조할 수 있으므로, 나중에 참조해야 할 상황에 대비해 특정 결정의 배경을 설명하는 좋은 설명문, 코멘트, 커밋 메시지를 남기는 것이 매우 중요합니다. 그룹 안에서만 검토할 MR 이라도 관련된 의사 결정을 모두 명시적으로 담아야 합니다.

아키텍처 이슈#

한 단위의 작업이 그룹 전체의 방향에 영향을 줄 만큼 커지기 시작하면, 기술적 방향을 논의할 아키텍처 이슈를 만드는 편이 좋습니다. 이 과정은 비공식적이며 공식 요구 사항이 없습니다. GitLab 프로젝트 안에 이슈를 만들어 진행할 작업 계획을 제안하고, 협업자를 초대해 함께 제안을 다듬습니다.

이런 구조를 통해 그룹은 제안된 변경을 검토하고, 피드백을 모으고, 반복 개선할 수 있습니다. 또한 기능 이슈의 코멘트 스레드나 MR 자체가 아니라 해당 이슈를 진실 공급원으로 삼을 수 있습니다. 논의를 돕기 위해 도식 같은 시각 자료를 추가하는 방안도 검토합니다. 예시로 CI/CD 카탈로그의 아키텍처 이슈를 참고할 수 있습니다.

설계 문서#

앞으로의 작업이 단일 그룹이나 Stage, 나아가 부서 전체(예를 들어 프론트엔드 팀 전체)에 영향을 줄 수 있다면 설계 문서(Design Document)가 필요할 가능성이 높습니다.

핸드북에 자세히 정리돼 있지만 간단히 말하면, 큰 변경을 제안하고 진행에 필요한 피드백과 지지를 모으는 가장 좋은 방법입니다. 이 문서는 버전 관리되고 시간이 지나며 계속 발전하며, 복잡한 이해를 조직 전체에 공유하는 좋은 수단입니다. 코치도 필요하므로 큰 변경 경험이 많은 사람을 참여시키는 좋은 계기가 됩니다. 이 프로세스는 모든 엔지니어링 부서가 공유하며 CTO가 소유합니다.

모든 설계 문서는 Architecture at GitLab 페이지에서 확인할 수 있습니다.

프론트엔드 RFC (더 이상 사용되지 않음)#

과거에는 큰 변경을 제안하고 부서 전체의 의견을 모으는 것을 목표로 한 Frontend RFC 프로젝트가 있었습니다. 이 프로젝트는 다음과 같은 이유로 더 이상 사용하지 않습니다.

1. 이 프로젝트에 생성된 이슈의 참여율이 매우 낮았습니다(20% 미만).
2. 논쟁적인 이슈는 해결 방법이 분명하지 않아 정체되곤 했습니다.
3. 완료된 이슈는 애초에 RFC가 필요하지 않은 경우가 많았습니다(작은 이슈).
4. 변경이 시간과 리소스 배분에 대한 고려 없이 "순진하게" 제안되는 경우가 많았습니다.

RFC를 만들었을 법한 대부분의 상황에서는 설계 문서로 대체할 수 있습니다. 설계 문서에는 자체 RFC가 붙기 때문입니다. 이렇게 하면 논의가 기술 설계를 중심으로 이뤄지고, RFC는 설계를 완성하기 위한 수단으로 자리 잡습니다.

프론트엔드 문서 항목#

문서에 아키텍처 절을 추가하는 것은 기존 아키텍처를 어떻게 사용하고 그 위에 무엇을 쌓을지 프론트엔드 엔지니어에게 알리는 방법입니다. 스스로 파악하기 어려운 애플리케이션 영역에 엔지니어를 "온보딩"할 때 활용합니다. 다른 팀에 영향이 없다면 소속 그룹의 아키텍처를 여기에 문서화하지 않도록 합니다.

선택 기준#

일반적으로 변경의 범위가 넓을수록 본인과 팀이 설계 문서의 도움을 받을 가능성이 높습니다. 또한 그 변경이 진정한 양방향 문 결정인지도 함께 고려합니다. 쉽게 되돌릴 수 있는 변경은 되돌릴 수 없는 변경보다 미리 고민할 것이 적습니다.

단일 마일스톤 안에서 끝낼 수 있는 작업은 머지 리퀘스트만으로 충분합니다. 여러 마일스톤이 걸리더라도 본인이 유일한 DRI 라면 이 역시 MR로 처리하는 편이 수월합니다.

DRI가 여러 명이라면 앞으로의 작업이 모두에게 분명한지 자문합니다. 작업이 복잡하고 서로 영향을 준다면 아키텍처 이슈 작업을 시작하기 전에 팀에서 기술 피드백을 모으는 방안을 검토합니다. 명확한 제안을 작성하고, 모든 이해관계자를 초기에 참여시키며, 이슈에서 내린 결정에 대해 스스로 책임을 집니다.

아주 작은 변경이 매우 넓은 영향을 줄 수도 있습니다. 예를 들어 ESLint 규칙 하나를 바꾸면 엔지니어링 전체에 영향을 주지만 설계 문서까지는 필요하지 않을 수 있습니다. Slack으로 제안(예를 들어 "X 규칙을 활성화하는 방안")을 공유해 관심도를 확인한 다음 MR을 생성하는 방법을 검토합니다. 마지막으로 적절한 채널에 널리 공유해 피드백을 모읍니다.

문서에서 특정 코드 패턴을 권장하려면, 제안한 변경을 적용한 MR을 작성해 부서 전체에 널리 공유하고 강한 반대가 없으면 머지합니다. 이 방식은 실행을 우선하므로 RFC보다 효율적이면서도, 모두가 참여했다고 느끼는 데 필요한 피드백을 모두 모읍니다.

기술 스택의 중대한 변경(Vue에서 React로, JavaScript에서 TypeScript로 등)을 제안하려면 먼저 Slack에서 관심도를 확인합니다. 지금 보이는 문제를 현재 기술 스택에서 해결할 수 있는지 항상 자문합니다. 이미 가진 도구로 문제를 해결하려는 시도가 우선이기 때문입니다. 백엔드나 QA 같은 다른 부서에도 기술 변경을 제안하는 명확한 프로세스는 없습니다. 이런 변경은 회사 차원의 막대한 투자가 필요하고, 엔지니어링 고위 임원의 참여 없이는 결정하기 어렵기 때문입니다.

대신 문제를 설명하고 현재 도구로 해결을 시도하는 설계 문서를 시작하는 방안을 검토합니다. 부서의 기여를 요청하고 철저히 조사합니다. 결과는 두 가지뿐입니다. 현재 도구로 문제를 해결할 수 있거나, 그렇지 않거나입니다. 해결할 수 있다면 스택을 통째로 바꾸지 않고 문제를 해결한 것이므로 팀에 큰 성과이고, 해결할 수 없다면 그 설계 문서가 기술 변경에 관한 더 큰 논의의 출발점이 됩니다.

위젯 아키텍처#

Plan Stage 는 오른쪽 사이드바를 위젯 단위로 구성하도록 리팩터링하고 있습니다. 위젯은 재사용 가능하고 페이지의 외부 Vue 애플리케이션이 사용할 수 있는 인터페이스를 노출하도록 고유한 아키텍처를 갖추고 있습니다. 자세한 내용은 위젯 아키텍처를 참고합니다.