InfoGrab DocsInfoGrab Docs

프론트엔드 개발 가이드라인

요약

이 문서는 GitLab 프론트엔드 팀 전반에서 일관성과 품질을 보장하기 위한 여러 가이드라인을 설명합니다. GitLab은 Ruby on Rails 위에 구축되어 있습니다. 자세한 내용은 Hamlit을 참고합니다. CSS에는 유틸리티 기반 CSS 방식을 사용합니다.

이 문서는 GitLab 프론트엔드 팀 전반에서 일관성과 품질을 보장하기 위한 여러 가이드라인을 설명합니다.

개요#

GitLab은 Ruby on Rails 위에 구축되어 있습니다. Haml과 Vue.js 기반의 JavaScript 프론트엔드를 사용합니다. Haml 페이지 위에 Vue를 언제 사용해야 할지 확실하지 않다면 이 설명을 참고합니다.

자세한 내용은 Hamlit을 참고합니다.

CSS에는 유틸리티 기반 CSS 방식을 사용합니다. 자세한 내용과 CSS 유틸리티가 정의된 위치는 이 가이드의 SCSS 스타일 섹션을 참고합니다.

또한 SCSS와 일반 JavaScript를 사용하며, 최신 ECMAScript 표준은 Babel로, ES 모듈 지원은 webpack으로 처리합니다.

API 호출에는 GraphQL을 첫 번째 선택지로 사용합니다. 새로운 단순 Haml 페이지를 만들 때나 코드베이스의 레거시 영역처럼 GitLab REST API를 사용하는 경우도 여전히 있지만, 가능하면 항상 GraphQL을 기본으로 사용합니다.

Vue의 클라이언트 측 상태 관리에는 기능의 구체적인 요구 사항에 따라 다음을 사용합니다.

  • Apollo (GraphQL에 의존하는 애플리케이션의 기본 선택지)
  • Pinia
  • 상태를 가지는 컴포넌트.

Vuex는 더 이상 사용되지 않으며, 가능한 경우 Vuex에서 마이그레이션합니다.

참고 자료: 상태 관리자 선택 기준

복사 문자열과 번역에는 프론트엔드 유틸리티를 사용할 수 있습니다. 자세한 내용은 번역을 위한 페이지 준비의 JavaScript 섹션을 참고합니다.

프론트엔드 에셋 작업에는 Node(v12.22.1 이상)와 Yarn(v1.10.0 이상)이 필요합니다. 설치 방법은 설치 가이드에서 확인할 수 있습니다.

상위 수준 개요#

GitLab 핵심 프론트엔드 코드는 app/assets/javascripts 아래에 있습니다.

GitLab은 Ruby on Rails 프레임워크를 사용하므로 Haml을 사용해 뷰에 Vue 애플리케이션을 주입합니다. 예를 들어 Rails 뷰에서 Vue 앱을 빌드하려면 app/views/projects/pipeline_schedules/index.html.haml과 같은 뷰를 구성합니다. 이 뷰 안에 #pipeline-schedules-app과 같은 id를 가진 요소를 추가합니다. 이 요소가 프론트엔드 코드의 마운트 지점이 됩니다.

애플리케이션 구조는 일반적으로 app/assets/javascripts/<feature-name> 패턴을 따릅니다. 예를 들어 특정 기능의 디렉터리는 app/assets/javascripts/ci/pipeline_schedules와 같은 형태입니다. 이러한 디렉터리 안에서는 코드를 components나 graphql 같은 하위 폴더로 나누어 기능을 구성하는 코드를 담습니다. 일반적인 구조는 다음과 같습니다.

  • feature_name/
    • components/ (기능을 구성하는 Vue 컴포넌트)
    • graphql/ (쿼리·뮤테이션)
    • utils/ (헬퍼 함수)
    • router/ (선택 사항: Vue Router 기반 앱에만 해당)
    • constants.js (공유 변수)
    • index.js (Vue 앱을 주입하는 파일)

기능을 구성하기 위해 "메인" 컴포넌트 역할을 하며 하위 컴포넌트를 가져오는 최상위 Vue 컴포넌트가 항상 존재합니다. 모든 경우에 Haml 뷰의 주입 지점(예: #pipeline-schedules-app)을 찾아 Vue 앱을 페이지에 마운트하는 동반 파일이 함께 있습니다. 이 파일의 이름은 index.js나 app.js인 경우가 많지만 자주 달라집니다.

이는 Vue 앱을 구성하는 app/assets/javascripts/ci/pipeline_schedules/mount_pipeline_schedules_app.js 같은 JavaScript 파일을 app/assets/javascripts/pages/projects/pipeline_schedules/index/index.js처럼 해당 Haml 뷰에 대응하는 페이지 번들로 가져와서 구현합니다.

기능에는 index, show, edit, new처럼 여러 라우트가 있는 경우가 많습니다. 이러한 경우 일반적으로 특정 라우트에 따라 서로 다른 Vue 애플리케이션을 주입합니다. app/assets/javascripts/pages 안의 폴더 구조가 이 구성을 반영합니다. 예를 들어 app/assets/javascripts/pages/<feature-name>/show 같은 하위 폴더는 Rails 컨트롤러 app/controllers/<controller-name>과 그 액션 def show; end에 대응합니다. 또는 index 라우트에 Vue 애플리케이션을 마운트하고 Vue Router로 클라이언트에서 라우팅을 처리할 수 있습니다.

각 최상위 폴더는 패키지이며, 어떤 패키지가 어떤 패키지를 가져올 수 있는지는 CI에서 강제합니다. 계층 구조와 이를 다루는 방법은 프론트엔드 패키지 경계를 참고합니다.

비전#

프론트엔드 엔지니어로서 사용자에게 만족스러운 경험을 제공하고자 합니다. 이 목표가 GitLab에서 구체적으로 어떻게 적용되는지 항상 고민해야 합니다. 훌륭한 GitLab 경험이란 사용자가 자신의 소프트웨어를 더 빠르고 더 확신을 가지고 출시하도록 돕는 것을 의미합니다. 따라서 부서의 미래를 좌우하는 선택을 마주할 때마다 이 점을 가장 먼저 떠올려야 합니다.

가치#

안정성(Stability), 속도(Speed), 유지보수성(Maintainability)의 세 가지 핵심 가치(SSM)를 정의합니다.

안정성#

속도도 대단히 중요하지만, GitLab은 이제 가장 작은 MVC조차 안정적이고 테스트되며 좋은 아키텍처를 갖춰야 하는 엔터프라이즈급 플랫폼이라고 봅니다. MVC라 하더라도 품질 저하, 낮은 성능, 혼란을 초래하거나 사용자 기대치를 떨어뜨릴 수 있는 코드는 머지하지 않습니다.

이는 사용자가 자신의 소프트웨어에 확신을 갖기를 바라는 핵심 가치의 연장선이며, 그러려면 사용자가 먼저 GitLab에 확신을 가져야 합니다. 즉, 자사 소프트웨어에 대한 스스로의 확신이 최대치여야 한다는 의미입니다.

속도#

사용자는 GitLab 애플리케이션을 손쉽게 탐색할 수 있어야 합니다. 이는 빠른 로드 시간, 찾기 쉬운 페이지, 명확한 UX, 그리고 마찰 없이 목표를 달성할 수 있다는 전반적인 감각을 뜻합니다.

또한 개발자도 그 속도를 체감하고 그 가치를 인정할 수 있기를 바랍니다. 이는 부서 전반에서 더 빠르게 성과를 내도록 돕는 프로세스, 도구, 문서에 많은 노력과 고민을 들여야 한다는 뜻입니다. 이는 엔지니어에게도 이익이지만, 품질 높은 기능을 더 빠른 주기로 받게 되는 사용자에게도 이익입니다.

유지보수성#

GitLab은 이제 대규모 엔터프라이즈급 소프트웨어이며, 최상의 경험을 제공하기 위해 복잡한 코드가 필요한 경우가 많습니다. 복잡성은 불가피하지만, 필요 이상으로 커지지 않도록 계속 경계해야 합니다. 이를 최소화하기 위해 복잡성을 캡슐화하여 코드베이스를 유지보수 가능한 상태로 만드는 데 집중합니다. 방법은 다음과 같습니다.

  • 자주 마주치는 문제를 해결하는 도구를 만들고 쉽게 찾을 수 있도록 합니다.
  • 문제 해결 방법에 대한 더 나은 문서를 작성합니다.
  • 코드베이스에 쉽게 추가하고 제거할 수 있는 느슨하게 결합된 컴포넌트를 작성합니다.
  • 더 이상 적합하지 않다고 판단한 오래된 기술이나 패턴을 제거합니다.

이러한 측면에 집중함으로써 엔지니어가 잘 정의된 경계 안에 복잡성을 가두고 이를 동료와 빠르게 공유할 수 있도록 하는 것을 목표로 합니다.

목표#

가치를 정의했으므로, 이 가치를 기반으로 목표를 세우고 GitLab에서 무엇을 달성하고자 하는지 정할 수 있습니다.

  • 가능한 한 낮은 FID, LCP 및 페이지 간 이동 시간
  • UI 조작 시 최소한의 페이지 새로 고침
  • 페이지당 Vue 애플리케이션 수를 최대한 줄이기
  • 단순한 페이지에는 Ruby ViewComponents를 활용하고 가능한 경우 Vue 오버헤드 피하기
  • Vuex에서 마이그레이션하되, 더 시급한 과제로 Apollo와 Vuex를 함께 사용하는 방식 중단
  • 코드베이스에서 jQuery 제거
  • 비주얼 테스트 프레임워크 추가
  • CSS 번들 크기를 최소 수준으로 축소
  • CSS의 인지 부담 감소 및 유지보수성 향상
  • 파이프라인 속도 개선
  • 문서를 갖춘 더 나은 공유 컴포넌트 세트 구축

GitLab 프론트엔드의 미래를 보는 관점은 프론트엔드 목표 섹션에 자세히 설명되어 있습니다.

첫 기여자#

처음 기여하는 경우 GitLab 개발에 기여를 참고합니다.

첫 머지 리퀘스트를 생성할 준비가 되었거나 GitLab 프론트엔드 워크플로를 다시 살펴봐야 한다면 시작하기를 참고합니다.

GitLab 프론트엔드 개발에 대한 안내형 소개가 필요하다면 6주 구성의 체계적인 커리큘럼을 제공하는 프론트엔드 온보딩 과정을 시청할 수 있습니다.

유용한 링크#

이니셔티브#

여러 부서에 영향을 주는 현재 프론트엔드 이니셔티브는 frontend-initiative 레이블이 붙은 에픽에서 확인할 수 있습니다.

테스트#

프론트엔드 테스트를 작성하는 방법, GitLab 테스트 스위트 실행 방법, 테스트 관련 이슈를 디버깅하는 방법을 다룹니다.

Pajamas 디자인 시스템#

기술 지침과 사용 지침을 갖춘 재사용 가능한 컴포넌트는 Pajamas Design System에서 확인할 수 있습니다.

프론트엔드 FAQ#

유용한 짧은 정보는 프론트엔드 FAQ에서 확인합니다.

국제화(i18n) 및 번역#

프론트엔드 국제화 지원은 GitLab을 사용자의 언어로 번역에서 설명합니다. 가이드의 외부화 부분은 사용할 수 있는 헬퍼와 메서드를 설명합니다.

문제 해결#

프론트엔드 개발 중 문제가 발생하면 이 문제 해결 가이드에서 해결 방법을 확인합니다.

브라우저 지원#

지원되는 브라우저는 요구 사항을 참고합니다.

프론트엔드 개발 가이드라인

GitLab v19.5
원문 보기

요약

이 문서는 GitLab 프론트엔드 팀 전반에서 일관성과 품질을 보장하기 위한 여러 가이드라인을 설명합니다. GitLab은 Ruby on Rails 위에 구축되어 있습니다. 자세한 내용은 Hamlit을 참고합니다. CSS에는 유틸리티 기반 CSS 방식을 사용합니다.

이 문서는 GitLab 프론트엔드 팀 전반에서 일관성과 품질을 보장하기 위한 여러 가이드라인을 설명합니다.

개요#

GitLab은 Ruby on Rails 위에 구축되어 있습니다. Haml과 Vue.js 기반의 JavaScript 프론트엔드를 사용합니다. Haml 페이지 위에 Vue를 언제 사용해야 할지 확실하지 않다면 이 설명을 참고합니다.

자세한 내용은 Hamlit을 참고합니다.

CSS에는 유틸리티 기반 CSS 방식을 사용합니다. 자세한 내용과 CSS 유틸리티가 정의된 위치는 이 가이드의 SCSS 스타일 섹션을 참고합니다.

또한 SCSS와 일반 JavaScript를 사용하며, 최신 ECMAScript 표준은 Babel로, ES 모듈 지원은 webpack으로 처리합니다.

API 호출에는 GraphQL을 첫 번째 선택지로 사용합니다. 새로운 단순 Haml 페이지를 만들 때나 코드베이스의 레거시 영역처럼 GitLab REST API를 사용하는 경우도 여전히 있지만, 가능하면 항상 GraphQL을 기본으로 사용합니다.

Vue의 클라이언트 측 상태 관리에는 기능의 구체적인 요구 사항에 따라 다음을 사용합니다.

  • Apollo (GraphQL에 의존하는 애플리케이션의 기본 선택지)
  • Pinia
  • 상태를 가지는 컴포넌트.

Vuex는 더 이상 사용되지 않으며, 가능한 경우 Vuex에서 마이그레이션합니다.

참고 자료: 상태 관리자 선택 기준

복사 문자열과 번역에는 프론트엔드 유틸리티를 사용할 수 있습니다. 자세한 내용은 번역을 위한 페이지 준비의 JavaScript 섹션을 참고합니다.

프론트엔드 에셋 작업에는 Node(v12.22.1 이상)와 Yarn(v1.10.0 이상)이 필요합니다. 설치 방법은 설치 가이드에서 확인할 수 있습니다.

상위 수준 개요#

GitLab 핵심 프론트엔드 코드는 app/assets/javascripts 아래에 있습니다.

GitLab은 Ruby on Rails 프레임워크를 사용하므로 Haml을 사용해 뷰에 Vue 애플리케이션을 주입합니다. 예를 들어 Rails 뷰에서 Vue 앱을 빌드하려면 app/views/projects/pipeline_schedules/index.html.haml과 같은 뷰를 구성합니다. 이 뷰 안에 #pipeline-schedules-app과 같은 id를 가진 요소를 추가합니다. 이 요소가 프론트엔드 코드의 마운트 지점이 됩니다.

애플리케이션 구조는 일반적으로 app/assets/javascripts/<feature-name> 패턴을 따릅니다. 예를 들어 특정 기능의 디렉터리는 app/assets/javascripts/ci/pipeline_schedules와 같은 형태입니다. 이러한 디렉터리 안에서는 코드를 components나 graphql 같은 하위 폴더로 나누어 기능을 구성하는 코드를 담습니다. 일반적인 구조는 다음과 같습니다.

  • feature_name/
    • components/ (기능을 구성하는 Vue 컴포넌트)
    • graphql/ (쿼리·뮤테이션)
    • utils/ (헬퍼 함수)
    • router/ (선택 사항: Vue Router 기반 앱에만 해당)
    • constants.js (공유 변수)
    • index.js (Vue 앱을 주입하는 파일)

기능을 구성하기 위해 "메인" 컴포넌트 역할을 하며 하위 컴포넌트를 가져오는 최상위 Vue 컴포넌트가 항상 존재합니다. 모든 경우에 Haml 뷰의 주입 지점(예: #pipeline-schedules-app)을 찾아 Vue 앱을 페이지에 마운트하는 동반 파일이 함께 있습니다. 이 파일의 이름은 index.js나 app.js인 경우가 많지만 자주 달라집니다.

이는 Vue 앱을 구성하는 app/assets/javascripts/ci/pipeline_schedules/mount_pipeline_schedules_app.js 같은 JavaScript 파일을 app/assets/javascripts/pages/projects/pipeline_schedules/index/index.js처럼 해당 Haml 뷰에 대응하는 페이지 번들로 가져와서 구현합니다.

기능에는 index, show, edit, new처럼 여러 라우트가 있는 경우가 많습니다. 이러한 경우 일반적으로 특정 라우트에 따라 서로 다른 Vue 애플리케이션을 주입합니다. app/assets/javascripts/pages 안의 폴더 구조가 이 구성을 반영합니다. 예를 들어 app/assets/javascripts/pages/<feature-name>/show 같은 하위 폴더는 Rails 컨트롤러 app/controllers/<controller-name>과 그 액션 def show; end에 대응합니다. 또는 index 라우트에 Vue 애플리케이션을 마운트하고 Vue Router로 클라이언트에서 라우팅을 처리할 수 있습니다.

각 최상위 폴더는 패키지이며, 어떤 패키지가 어떤 패키지를 가져올 수 있는지는 CI에서 강제합니다. 계층 구조와 이를 다루는 방법은 프론트엔드 패키지 경계를 참고합니다.

비전#

프론트엔드 엔지니어로서 사용자에게 만족스러운 경험을 제공하고자 합니다. 이 목표가 GitLab에서 구체적으로 어떻게 적용되는지 항상 고민해야 합니다. 훌륭한 GitLab 경험이란 사용자가 자신의 소프트웨어를 더 빠르고 더 확신을 가지고 출시하도록 돕는 것을 의미합니다. 따라서 부서의 미래를 좌우하는 선택을 마주할 때마다 이 점을 가장 먼저 떠올려야 합니다.

가치#

안정성(Stability), 속도(Speed), 유지보수성(Maintainability)의 세 가지 핵심 가치(SSM)를 정의합니다.

안정성#

속도도 대단히 중요하지만, GitLab은 이제 가장 작은 MVC조차 안정적이고 테스트되며 좋은 아키텍처를 갖춰야 하는 엔터프라이즈급 플랫폼이라고 봅니다. MVC라 하더라도 품질 저하, 낮은 성능, 혼란을 초래하거나 사용자 기대치를 떨어뜨릴 수 있는 코드는 머지하지 않습니다.

이는 사용자가 자신의 소프트웨어에 확신을 갖기를 바라는 핵심 가치의 연장선이며, 그러려면 사용자가 먼저 GitLab에 확신을 가져야 합니다. 즉, 자사 소프트웨어에 대한 스스로의 확신이 최대치여야 한다는 의미입니다.

속도#

사용자는 GitLab 애플리케이션을 손쉽게 탐색할 수 있어야 합니다. 이는 빠른 로드 시간, 찾기 쉬운 페이지, 명확한 UX, 그리고 마찰 없이 목표를 달성할 수 있다는 전반적인 감각을 뜻합니다.

또한 개발자도 그 속도를 체감하고 그 가치를 인정할 수 있기를 바랍니다. 이는 부서 전반에서 더 빠르게 성과를 내도록 돕는 프로세스, 도구, 문서에 많은 노력과 고민을 들여야 한다는 뜻입니다. 이는 엔지니어에게도 이익이지만, 품질 높은 기능을 더 빠른 주기로 받게 되는 사용자에게도 이익입니다.

유지보수성#

GitLab은 이제 대규모 엔터프라이즈급 소프트웨어이며, 최상의 경험을 제공하기 위해 복잡한 코드가 필요한 경우가 많습니다. 복잡성은 불가피하지만, 필요 이상으로 커지지 않도록 계속 경계해야 합니다. 이를 최소화하기 위해 복잡성을 캡슐화하여 코드베이스를 유지보수 가능한 상태로 만드는 데 집중합니다. 방법은 다음과 같습니다.

  • 자주 마주치는 문제를 해결하는 도구를 만들고 쉽게 찾을 수 있도록 합니다.
  • 문제 해결 방법에 대한 더 나은 문서를 작성합니다.
  • 코드베이스에 쉽게 추가하고 제거할 수 있는 느슨하게 결합된 컴포넌트를 작성합니다.
  • 더 이상 적합하지 않다고 판단한 오래된 기술이나 패턴을 제거합니다.

이러한 측면에 집중함으로써 엔지니어가 잘 정의된 경계 안에 복잡성을 가두고 이를 동료와 빠르게 공유할 수 있도록 하는 것을 목표로 합니다.

목표#

가치를 정의했으므로, 이 가치를 기반으로 목표를 세우고 GitLab에서 무엇을 달성하고자 하는지 정할 수 있습니다.

  • 가능한 한 낮은 FID, LCP 및 페이지 간 이동 시간
  • UI 조작 시 최소한의 페이지 새로 고침
  • 페이지당 Vue 애플리케이션 수를 최대한 줄이기
  • 단순한 페이지에는 Ruby ViewComponents를 활용하고 가능한 경우 Vue 오버헤드 피하기
  • Vuex에서 마이그레이션하되, 더 시급한 과제로 Apollo와 Vuex를 함께 사용하는 방식 중단
  • 코드베이스에서 jQuery 제거
  • 비주얼 테스트 프레임워크 추가
  • CSS 번들 크기를 최소 수준으로 축소
  • CSS의 인지 부담 감소 및 유지보수성 향상
  • 파이프라인 속도 개선
  • 문서를 갖춘 더 나은 공유 컴포넌트 세트 구축

GitLab 프론트엔드의 미래를 보는 관점은 프론트엔드 목표 섹션에 자세히 설명되어 있습니다.

첫 기여자#

처음 기여하는 경우 GitLab 개발에 기여를 참고합니다.

첫 머지 리퀘스트를 생성할 준비가 되었거나 GitLab 프론트엔드 워크플로를 다시 살펴봐야 한다면 시작하기를 참고합니다.

GitLab 프론트엔드 개발에 대한 안내형 소개가 필요하다면 6주 구성의 체계적인 커리큘럼을 제공하는 프론트엔드 온보딩 과정을 시청할 수 있습니다.

유용한 링크#

이니셔티브#

여러 부서에 영향을 주는 현재 프론트엔드 이니셔티브는 frontend-initiative 레이블이 붙은 에픽에서 확인할 수 있습니다.

테스트#

프론트엔드 테스트를 작성하는 방법, GitLab 테스트 스위트 실행 방법, 테스트 관련 이슈를 디버깅하는 방법을 다룹니다.

Pajamas 디자인 시스템#

기술 지침과 사용 지침을 갖춘 재사용 가능한 컴포넌트는 Pajamas Design System에서 확인할 수 있습니다.

프론트엔드 FAQ#

유용한 짧은 정보는 프론트엔드 FAQ에서 확인합니다.

국제화(i18n) 및 번역#

프론트엔드 국제화 지원은 GitLab을 사용자의 언어로 번역에서 설명합니다. 가이드의 외부화 부분은 사용할 수 있는 헬퍼와 메서드를 설명합니다.

문제 해결#

프론트엔드 개발 중 문제가 발생하면 이 문제 해결 가이드에서 해결 방법을 확인합니다.

브라우저 지원#

지원되는 브라우저는 요구 사항을 참고합니다.