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와 Babel을 통해 지원되는 최신 ECMAScript 표준의 일반 JavaScript, 그리고 webpack을 통한 ES 모듈 지원을 사용합니다.

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

Vue에서의 클라이언트 측 상태 관리에는 기능의 특정 요구 사항에 따라 다음을 사용합니다:

  • Apollo (GraphQL에 의존하는 애플리케이션의 기본 선택)

  • Pinia

  • 상태 저장 컴포넌트.

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로 명명되지만 자주 다를 수 있음)이 있습니다.

이는 app/assets/javascripts/ci/pipeline_schedules/mount_pipeline_schedules_app.js(Vue 앱을 설정하는 파일)와 같은 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로 클라이언트 측 라우팅을 처리할 수 있습니다.

비전#

프론트엔드 엔지니어로서 우리는 사용자에게 즐거운 경험을 제공하기 위해 노력합니다. 이것이 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.2
원문 보기
요약

이 문서는 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와 Babel을 통해 지원되는 최신 ECMAScript 표준의 일반 JavaScript, 그리고 webpack을 통한 ES 모듈 지원을 사용합니다.

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

Vue에서의 클라이언트 측 상태 관리에는 기능의 특정 요구 사항에 따라 다음을 사용합니다:

  • Apollo (GraphQL에 의존하는 애플리케이션의 기본 선택)

  • Pinia

  • 상태 저장 컴포넌트.

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로 명명되지만 자주 다를 수 있음)이 있습니다.

이는 app/assets/javascripts/ci/pipeline_schedules/mount_pipeline_schedules_app.js(Vue 앱을 설정하는 파일)와 같은 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로 클라이언트 측 라우팅을 처리할 수 있습니다.

비전#

프론트엔드 엔지니어로서 우리는 사용자에게 즐거운 경험을 제공하기 위해 노력합니다. 이것이 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을 당신의 언어로 번역하기에서 설명합니다. 가이드의 외부화 부분은 사용 가능한 헬퍼/메서드를 설명합니다.

트러블슈팅#

프론트엔드 개발 문제가 발생했나요? 이슈를 해결하는 데 도움이 되는 이 트러블슈팅 가이드를 확인하세요.

브라우저 지원#

지원되는 브라우저는 요구 사항을 참조하세요.