• 결정 문서화
  • 병합 요청
  • 아키텍처 이슈
  • 설계 문서
  • Frontend RFC(더 이상 사용되지 않음)
  • Frontend 문서 항목
  • 어떤 것을 선택할까요?
• 위젯 아키텍처

아키텍처

GitLab에서는 전용 “소프트웨어 아키텍트”가 없습니다. 모든 사람은 자신의 결정을 내리고 적절하게 문서화할 것을 권장받습니다. 이러한 결정을 어떻게 하고 어디에 문서화해야 할지 알아보려면 계속 읽어보세요.

결정 문서화

새로운 기능을 구축할 때 구축할 내용의 범위와 규모를 고려하세요. 답에 따라 여러 도구나 프로세스가 여러분의 노력을 지원할 수 있습니다. 우리는 기능을 구축하는 프로세스를 가능한 한 효율적으로 유지하기 위해 노력하고 있습니다. 일반적인 규칙으로, 시간 소모가 많은 해결책의 추가적인 지원과 구조가 필요하지 않은 한 가능한 가장 간단한 프로세스를 사용하세요.

병합 요청

변경 사항이 그룹 내에서 한정되거나 단일 기여자가 있는 경우 아키텍처 결정의 최소한의 문서화는 커밋이며 이에 이은 병합 요청(MR)입니다. MR 또는 커밋은 병합된 후에도 참조될 수 있으므로 나중에 참조할 필요가 있는 경우 특정 결정을 설명하는 좋은 설명, 코멘트 및 커밋 메시지를 남기는 것이 중요합니다. 그룹 내에서 검토될 목적으로 의도된 MR조차도 모든 관련 결정 사항을 명시적으로 포함해야 합니다.

아키텍처 이슈

작업 단위가 충분히 커져 전체 그룹의 방향에 영향을 줄 수 있는 경우 기술적 방향을 논의하기 위해 아키텍처 이슈를 만드는 것이 좋은 아이디어일 수 있습니다. 이 프로세스는 비공식적이며 공식적인 요구 사항이 없습니다. 수행할 작업에 대한 계획을 제안하고 협업자를 초청하여 제안을 함께 정제할 수 있는 GitLab 프로젝트 내에서 이슈를 만드세요.

이 구조를 사용하면 그룹이 제안된 변경 사항을 신중하게 고려하고 피드백을 모으고 반복할 수 있습니다. 또한 이를 사용하여 기능 이슈나 MR의 댓글 스레드 대신 진실의 원천으로 사용할 수 있습니다. 토의를 용이하게 하기 위해 스키마와 같은 시각적 지원을 추가하는 것을 고려해보세요. 예를 들어, CI/CD 카탈로그의 아키텍처 이슈를 참조할 수 있습니다.

설계 문서

앞으로의 작업이 하나 이상의 그룹이나 스테이지 또는 아마도 전체 부서(예: Frontend 팀 전체)에 영향을 줄 수 있다면 설계 문서가 필요할 가능성이 높습니다.

이는 설명이 잘 된 핸드북에 자세히 기술되어 있지만 간략히 언급하면, 이것은 대형 변화사항을 제안하고 필요한 피드백을 수집하고 앞으로 나아가기 위한 최고의 방법입니다. 이러한 문서들은 버전이 관리되며 시간이 흐름에 따라 계속 발전하며 조직 전체에 복잡한 이해를 공유하는 좋은 방법입니다. 또한 대형 변화에 경험이 많은 사람을 관여시키는 것은 좋은 방법입니다. 이 프로세스는 모든 엔지니어링 부서에 공유되며 CTO가 소유하고 있습니다.

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

Frontend RFC(더 이상 사용되지 않음)

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

1. 이 프로젝트에서 생성된 이슈의 참여율이 매우 낮았습니다 (20% 미만)
2. 논란이 되는 이슈들은 명확한 해결책이 없이 멈추기 마련이었습니다
3. 완료된 이슈들은 일반적으로 처음부터 RFC가 필요한 작은 문제가 아니었습니다
4. 변경 사항이 종종 명확한 시간 및 리소스 할당 없이 “순진하게” 제안되었습니다

우리가 RFC를 생성했을만큼인 상황에서는 대부분 설계 문서 대신 사용할 수 있습니다. 이는 대화를 기술적 설계 중심으로 만들고 RFC는 설계 완료를 더 진행하기 위한 방법일 뿐입니다.

Frontend 문서 항목

문서에 아키텍처 섹션을 추가하는 것은 Frontend 엔지니어들에게 기존 아키텍처를 어떻게 사용하거나 이에 더 나은 점을 추가할 수 있는 방법을 알려주는 것입니다. 다른 팀에 영향을 미치지 않는다면 귀하의 그룹 아키텍처를 여기에 문서화하는 것을 피하려고 하세요.

어떤 것을 선택할까요?

일반적인 규칙으로, 변경 사항의 범위가 넓을수록 설계 문서를 통해 귀하와 귀하의 팀이 이익을 얻을 가능성이 높습니다. 또한 변경 사항이 진정한 “양방향 문” 결정인지도 고려하세요: 쉽게 되돌릴 수 있는 변경 사항은 무척 앞을 생각하는 것보다 적은 시간을 요구합니다.

하나의 마일스톤 내에서 달성할 수 있는 작업은 아마 병합 요청만으로 충분할 것입니다. 여러 마일스톤이 걸릴 수 있는 작업이지만 귀하가 유일한 DRI(Directly Responsible Individual)인 경우에도 병합 요청을 통해 쉽게 처리할 수 있을 것입니다.

여러 DRIs가 관련된 경우, 진행할 작업이 모든 사람에게 명확한지 스스로에게 물어보세요. 귀하가 하는 작업이 복잡하고 서로 영향을 미친다면 아키텍처 이슈에 대한 기술적 피드백을 조직 전체에게 수집할 수 있는지 미리 고려하세요. 명확한 제안을 작성하고 모든 이해관계자를 초기에 관여시키고 이슈에서 내린 결정에 대해 책임감을 갖도록 해보세요.

매우 작은 변경 사항이 매우 큰 영향을 미칠 수 있습니다. 예를 들어, ESLint 규칙을 변경하면 엔지니어링 전부에 영향을 미칠 수 있지만 설계 문서가 필요하지 않을 수도 있습니다. 관심을 끌기 위해 제안 내용을 Slack을 통해 보내고(“X 규칙을 활성화해야 할까요?”) 그런 다음 MR을 생성하세요. 마지막으로 적절한 채널에 널리 공유하여 피드백을 수집하세요.

문서에서 특정 코드 패턴을 추천하려면 제안한 변경 사항을 적용하는 MR을 작성하고 해당 부서와 널리 공유하세요. 강력한 반대 이의가 제기되지 않는다면 변경 사항을 병합하는 것이 좋습니다. 이것은 모든 사람을 포함할 필요가 있는 피드백을 모두 수집하면서도 행동을 선호하는 경향이 있어서 RFC보다 효율적입니다.

기술 스택에 대한 중대한 변경을 제안하고 싶다면 (Vue에서 React로, JavaScript에서 TypeScript로 등), 관심을 끌기 위해 먼저 Slack을 통해 연락해보세요. 항상 자신에게 물어보세요 귀하가 본 문제를 현재의 기술 스택으로 해결할 수 있는지 여부를(“우리가 이미 가진 도구로 문제를 해결하려고 해야 합니다”). 백엔드나 품질 보증(QA)과 같은 다른 부서들도 기술적 변경 사항을 제안하는 명확한 프로세스가 없습니다. 이는 회사에서 막대한 투자가 필요하며 고위 경영진의 관여 없이는 결정될 수 없기 때문입니다.

대신에 문제를 설명하고 현재의 도구로 문제를 해결하려고 노력하는 설계 문서를 작성해보세요. 회사 내에서 기여를 초대하고 이에 대해 철저히 연구해보세요. 왜냐하면 두 가지 결과만 나올 수 있기 때문입니다. 문제를 현재의 도구로 해결할 수 있다거나 해결할 수 없을 것입니다. 만약 해결할 수 있다면, 이것은 우리 팀들에게 큰 이득입니다. 왜냐하면 우리 스택을 완전히 변경할 필요 없이 문제를 해결했기 때문이고, 해결할 수 없다면 설계 문서가 기술적 변경 주변에서 큰 대화의 시작점이 될 수 있습니다.

위젯 아키텍처

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