GitLab에는 전담 "소프트웨어 아키텍트"가 없습니다. 모든 구성원이 스스로 결정을 내리고 적절하게 문서화하도록 권장됩니다. 이러한 결정을 어떻게, 어디에 문서화할지 알아보세요.

결정 문서화#

새로운 기능을 구축할 때는 구축하려는 작업의 범위와 규모를 고려하세요. 그 답에 따라 작업을 지원할 수 있는 여러 도구나 프로세스가 있습니다. 우리는 기능 구축 프로세스를 가능한 한 효율적으로 유지하는 것을 목표로 합니다. 일반적인 규칙으로, 더 많은 시간이 소요되는 솔루션의 추가적인 지원과 구조가 필요하지 않은 한 가능한 한 가장 간단한 프로세스를 사용하세요.

머지 리퀘스트#

변경 사항이 그룹 내로 제한되거나 단일 기여자가 있는 경우, 아키텍처 결정에 대한 가장 작은 문서화는 커밋이며, 이를 확장하면 머지 리퀘스트(MR)입니다. MR 또는 커밋은 병합된 후에도 참조할 수 있으므로, 나중에 참조해야 할 경우를 대비하여 특정 결정을 설명하는 좋은 설명, 코멘트, 커밋 메시지를 남기는 것이 중요합니다. 그룹 내에서 리뷰될 의도로 만들어진 MR이라도 모든 관련 의사결정을 명시적으로 포함해야 합니다.

아키텍처 이슈#

작업 단위가 그룹 전체의 방향에 영향을 미칠 만큼 커지면, 기술적 방향을 논의하기 위한 아키텍처 이슈를 생성하는 것이 좋습니다. 이 프로세스는 비공식적이며 공식적인 요구 사항이 없습니다. GitLab 프로젝트 내에서 이슈를 생성하여 수행할 작업에 대한 계획을 제안하고 협업자를 초대하여 함께 제안을 다듬어 나갈 수 있습니다.

이 구조를 통해 그룹은 제안된 변경 사항을 검토하고, 피드백을 수집하고, 반복할 수 있습니다. 또한 기능 이슈의 코멘트 스레드나 MR 자체가 아닌 이슈를 단일 진실 공급원(Single Source Of Truth, SSOT)으로 사용할 수 있습니다. 논의를 원활하게 하기 위해 스키마와 같은 시각적 자료를 추가하는 것을 고려해보세요. 예를 들어, 이 CI/CD Catalog의 아키텍처 이슈를 참고할 수 있습니다.

디자인 문서#

앞으로의 작업이 단일 그룹, Stage 또는 잠재적으로 전체 부서(예: 프론트엔드 팀 전체)에 영향을 미칠 수 있는 경우, 디자인 문서가 필요할 가능성이 높습니다.

이는 핸드북에 잘 문서화되어 있지만, 간략히 말씀드리자면, 디자인 문서는 대규모 변경 사항을 제안하고 진행에 필요한 피드백과 지원을 수집하는 가장 좋은 방법입니다. 이러한 문서는 버전 관리가 되고, 시간이 지남에 따라 계속 발전하며, 조직 전체에 복잡한 이해를 공유하는 훌륭한 방법입니다. 또한 코치가 필요하며, 이는 대규모 변경 사항에 많은 경험이 있는 사람을 참여시키는 훌륭한 방법입니다. 이 프로세스는 모든 엔지니어링 부서가 공유하며 CTO가 소유합니다.

모든 디자인 문서를 보려면 GitLab 아키텍처 페이지를 확인할 수 있습니다.

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

과거에는 프론트엔드 RFC 프로젝트가 있었으며, 이 프로젝트의 목적은 대규모 변경 사항을 제안하고 전체 부서의 의견을 수렴하는 것이었습니다. 이 프로젝트는 몇 가지 이유로 더 이상 사용되지 않습니다:

• 이 프로젝트에서 생성된 이슈의 참여율이 매우 낮았습니다 (20% 미만)

• 논란이 많은 이슈는 해결 방법이 명확하지 않아 중단되었습니다

• 완료된 이슈는 처음부터 RFC가 필요하지 않은 경우가 많았습니다 (소규모 이슈)

• 변경 사항은 명확한 시간 및 리소스 할당 없이 "순진하게" 제안되는 경우가 많았습니다

RFC를 생성했을 대부분의 경우, 대신 디자인 문서를 사용할 수 있으며, 디자인 문서에는 자체 RFC가 첨부됩니다. 이를 통해 대화가 기술적 디자인을 중심으로 이루어지며, RFC는 디자인 완성을 위한 수단에 불과합니다.

프론트엔드 문서의 항목 추가#

문서에 아키텍처 섹션을 추가하는 것은 프론트엔드 엔지니어에게 기존 아키텍처를 사용하거나 그 위에 구축하는 방법을 알려주는 방법입니다. 자명하지 않을 수 있는 애플리케이션의 일부에 엔지니어를 "온보딩"하는 데 도움이 되도록 활용하세요. 다른 팀에 영향을 주지 않는 경우 그룹의 아키텍처를 여기에 문서화하는 것은 피하세요.

어느 것을 선택할까요?#

일반적인 규칙으로, 변경 사항의 범위가 넓을수록 디자인 문서가 여러분과 팀에게 더 유익할 가능성이 높습니다. 또한 변경 사항이 진정한 양방향 결정인지도 고려하세요: 쉽게 되돌릴 수 있는 변경 사항은 그렇지 않은 변경 사항보다 미리 덜 고려해도 됩니다.

단일 마일스톤 내에서 완료할 수 있는 작업은 머지 리퀘스트만 필요할 수 있습니다. 여러 마일스톤이 필요하지만 여러분이 유일한 DRI(Directly Responsible Individual)인 작업도 MR을 통해 더 쉽게 수행할 수 있습니다.

여러 DRI가 관여된 경우, 앞으로의 작업이 모두에게 명확한지 스스로에게 물어보세요. 작업이 복잡하고 서로 영향을 미치는 경우, 아키텍처 이슈 작업을 시작하기 전에 팀에서 기술적 피드백을 수집하는 것을 고려하세요. 명확한 제안을 작성하고, 모든 이해관계자를 일찍 참여시키며, 이슈에서 내린 결정에 대해 서로 책임을 지세요.

매우 작은 변경 사항이 매우 넓은 영향을 미칠 수 있습니다. 예를 들어, ESLint 규칙 변경은 전체 엔지니어링에 영향을 미치지만 디자인 문서가 필요하지 않을 수 있습니다. Slack을 통해 제안을 공유하여 관심도를 측정하고 ("X 규칙을 활성화해야 할까요?") 그냥 MR을 생성하는 것을 고려하세요. 마지막으로, 피드백을 수집하기 위해 적절한 채널에 널리 공유하세요.

문서에서 특정 코드 패턴을 권장하려면, 제안된 변경 사항을 적용하는 MR을 작성하고, 부서와 널리 공유하며, 강력한 반대 의견이 없으면 변경 사항을 병합할 수 있습니다. 이 방법은 행동 편향으로 인해 RFC보다 효율적이며, 모든 사람이 포함되었다고 느끼는 데 필요한 모든 피드백을 수집합니다.

기술 스택에 대한 대규모 변경(Vue에서 React로, JavaScript에서 TypeScript로 등)을 제안하려면, Slack에서 관심도를 측정하는 것으로 시작하세요. 항상 현재 기술 스택으로 문제를 해결할 수 있는지 스스로에게 물어보세요. 이미 가지고 있는 도구로 문제를 해결하려고 항상 시도해야 하기 때문입니다. 백엔드 및 QA와 같은 다른 부서도 기술 변경을 제안하는 명확한 프로세스가 없습니다. 이러한 변경은 회사의 막대한 투자가 필요하며, 엔지니어링의 고위 임원을 포함하지 않고는 결정될 수 없기 때문입니다.

대신, 문제를 설명하고 현재 도구로 해결하려는 디자인 문서를 시작하는 것을 고려하세요. 부서의 기여를 초대하고 이를 철저히 연구하세요. 두 가지 결과만 가능하기 때문입니다. 문제를 현재 도구로 해결할 수 있거나 없거나입니다. 해결할 수 있다면, 스택을 완전히 변경하지 않고도 문제를 해결했으므로 팀에게 큰 승리입니다. 해결할 수 없다면, 디자인 문서가 기술 변경에 관한 더 큰 대화의 시작이 될 수 있습니다.

위젯 아키텍처#

Plan Stage는 위젯으로 구성된 오른쪽 사이드바를 리팩토링하고 있습니다. 위젯은 재사용 가능하고 페이지의 외부 Vue 애플리케이션에서 사용할 수 있는 인터페이스를 노출하기 위한 특정 아키텍처를 가지고 있습니다. 위젯 아키텍처에 대해 자세히 알아보세요.