• 결정 문서화
  • 병합 요청
  • 아키텍처 이슈
  • 디자인 문서
  • 프론트엔드 RFC(사용 중단)
  • 프론트엔드 문서의 항목
  • 무엇을 선택해야 할까요?
• 위젯 아키텍처

아키텍처

GitLab에서는 전담 “소프트웨어 아키텍트”가 없습니다. 모든 사람이 자신의 결정을 내리고 적절하게 문서화하도록 권장됩니다. 이러한 결정을 어떻게 또는 어디에 문서화할 수 있는지 알고 싶다면 계속 읽어주세요.

결정 문서화

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

병합 요청

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

아키텍처 이슈

작업 단위가 커져서 전체 그룹의 방향성에 영향을 미칠 수 있을 때, 기술 방향을 논의하기 위해 아키텍처 이슈를 만드는 것이 좋습니다. 이 과정은 비공식적이며 공식 요구 사항이 없습니다. GitLab 프로젝트 내에서 작업 계획을 제안하는 이슈를 만들고, 제안을 세부 조정하기 위해 협력자를 초대하세요.

이 구조는 그룹이 제안된 변화를 깊이 있게 사고하고, 피드백을 수집하고 반복할 수 있도록 합니다. 또한, 이슈를 기능 이슈나 MR 자체의 댓글 스레드가 아닌 사실의 출처로 사용할 수 있게 해줍니다. 논의를 촉진하기 위해 어떤 형태의 시각적 지원(스키마 등)을 추가하는 것을 고려하세요. 예를 들어, 이 CI/CD 카탈로그의 아키텍처 이슈를 참조할 수 있습니다.

디자인 문서

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

이것은 핸드북에 잘 문서화되어 있지만, 간단히 언급하자면, 이는 대규모 변경을 제안하고 앞으로 나아가기 위한 피드백과 지원을 수집하는 가장 좋은 방법입니다. 이러한 문서는 버전 제어가 가능하며 시간이 지남에 따라 발전하며, 전체 조직에 걸쳐 복잡한 이해를 공유하는 좋은 방법입니다. 또한, 코치가 필요하며, 이는 대규모 변경에 대한 많은 경험을 가진 사람을 참여시키는 좋은 방법입니다. 이 과정은 모든 엔지니어링 부서에서 공유되며 CTO가 소유하고 있습니다.

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

프론트엔드 RFC(사용 중단)

과거에 우리는 부서 전체의 의견을 얻고 더 큰 변경을 제안하기 위한 프론트엔드 RFC 프로젝트를 가졌습니다. 이 프로젝트는 몇 가지 이유로 더 이상 사용되지 않습니다:

1. 이 프로젝트에서 생성된 이슈의 참여율이 매우 낮았습니다(20% 미만).
2. 논란이 되는 이슈는 명확한 해결 방법 없이 정체되었습니다.
3. 완료된 이슈는 종종 처음부터 RFC가 필요하지 않았습니다(작은 이슈)
4. 변경 사항은 종종 명확한 시간과 자원 배분 없이 “단순히” 제안되었습니다.

대부분의 경우 RFC를 작성했어야 하는 경우, 디자인 문서를 대신 사용할 수 있습니다. 디자인 문서에는 자체 RFC가 첨부됩니다. 이렇게 하면 대화가 기술 디자인을 중심으로 이루어지고, RFC는 디자인 완료를 촉진하는 방법일 뿐입니다.

프론트엔드 문서의 항목

문서에 아키텍처 섹션을 추가하는 것은 프론트엔드 엔지니어에게 기존 아키텍처를 어떻게 사용하거나 구축할 수 있는지를 알려주는 방법입니다. 이를 통해 자명하지 않을 수 있는 애플리케이션의 일부에 엔지니어를 “온보드”하는 데 도움을 줍니다. 다른 팀에 영향이 없는 경우, 귀하의 그룹 아키텍처를 문서화하는 것을 피하십시오.

무엇을 선택해야 할까요?

일반적으로 변경 사항의 범위가 넓을수록 귀하와 귀하의 팀은 설계 문서의 혜택을 받을 가능성이 높습니다. 또한 귀하의 변경이 진정한 양방향 문 결정인지 고려하십시오: 쉽게 되돌릴 수 있는 변경 사항은 그렇지 않은 것보다 덜 생각을 요합니다.

단일 마일스톤 내에서 달성할 수 있는 작업은 아마도 병합 요청만 필요할 것입니다. 여러 마일스톤이 걸릴 수 있는 작업에서 귀하만이 DRI인 경우 MRs을 통해 더 쉽게 처리될 수 있습니다.

여러 DRI가 관련된 경우, 앞으로의 작업이 모두에게 명확한지 스스로에게 물어보십시오. 귀하가 하는 일이 복잡하고 서로에게 영향을 미친다면, 아키텍처 문제에 대해 작업을 시작하기 전에 팀으로부터 기술적인 피드백을 모으는 것을 고려하십시오. 명확한 제안을 작성하고, 모든 이해당사자를 조기에 포함시키며, 문제에 대한 결정에 대해 스스로 책임을 지십시오.

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

문서에서 특정 코드 패턴을 권장하려면 제안된 변경 사항을 적용하는 MR을 작성하고 부서와 널리 공유하며 강력한 이의 제기가 없으면 변경 사항을 병합하세요. 이는 모든 피드백을 포함하는 동시에 행동 편향 때문에 RFC보다 효율적입니다.

기술 스택(예: Vue에서 React, JavaScript에서 TypeScript 등)에 대한 주요 변경 사항을 제안하고 싶다면, 관심을 평가하기 위해 Slack에서 연락하는 것으로 시작하세요. 현재의 기술 스택으로 문제를 해결할 수 있는지 항상 스스로에게 물어보세요. 우리는 항상 기존의 도구로 문제를 해결하려고 해야 합니다. 백엔드 및 QA와 같은 다른 부서는 기술 변경을 제안하는 명확한 프로세스가 없습니다. 이는 이러한 변경이 회사의 막대한 투자를 요구하며 아마도 엔지니어링의 고위 간부가 참여하지 않고는 결정될 수 없기 때문입니다.

대신, 문제를 설명하고 현재의 도구로 해결하려고 시도하는 설계 문서를 시작하는 것을 고려하십시오. 부서의 기여를 초대하고 이를 철저히 조사하십시오. 결과는 단 두 가지일 수 있습니다. 문제 를 현재 도구로 해결할 수 있거나 해결할 수 없습니다. 해결할 수 있다면, 이는 우리의 스택을 완전히 변경할 필요없이 문제를 해결했으므로 우리 팀에 큰 승리가 됩니다. 해결할 수 없다면, 설계 문서는 기술 변경에 대한 더 큰 대화의 시작이 될 수 있습니다.

위젯 아키텍처

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