フロントエンド開発ガイドライン

この文書では、GitLabフロントエンドチーム全体の一貫性と品質を保証するための様々なガイドラインについて説明します。

概要

GitLabはRuby on Railsの上に構築されています。Hamlと Vue.jsによるJavaScriptベースのフロントエンドを使用しています。Haml-pageの上でVueを使うタイミングがわからない場合は、こちらの説明をお読みください。

Hamlitを使用する際に生じる制限に注意してください。

CSSに関しては、私たちはutilsベースのCSSアプローチを使っています。GitLab には独自の CSS utils があり、gitlab-ui プロジェクトの内部でパッケージ化され、リポジトリやUNPKG で見ることができます。SCSS クラスを追加したり使用したりする前に、これらを使用することをお勧めします。

また、私たちはSCSSとプレーンなJavaScriptを使用しており、Babelと webpackによるESモジュールのサポートによって最新のECMAScript標準をサポートしています。

APIコールを行う際、私たちはGraphQLを第一選択として使用しています。新しいシンプルなHAMLページを作成するときやコードベースのレガシーな部分など、GitLab REST APIを使うインスタンスもまだありますが、可能な限り常にGraphQLをデフォルトにすべきです。

私たちはApolloをグローバルステートマネージャーとGraphQLクライアントとして使っています。VueXはコードベース全体でまだ使用されていますが、推奨されるグローバルステートマネージャではなくなりました。VueXとApolloを一緒に使うべきではありませんし、可能な限り新しいVueXストアの追加は避けるべきです。

文字列のコピーと翻訳については、フロントエンドのユーティリティを用意しています。詳しくは、Preparing a page for translationのJavaScriptセクションをご覧ください。

フロントエンドのアセットを使用するには、Node（v12.22.1以上）とYarn（v1.10.0以上）が必要です。これらのインストール方法については、インストールガイドをご覧ください。

ビジョン

フロントエンドエンジニアとして、私たちはユーザーに快適な体験を提供するよう努めています。GitLabの素晴らしい体験とは、私たちのユーザーが自分のプロジェクトをより速く、より自信を持って出荷できるようにすることです。つまり、私たちの部署の将来について選択を迫られたときはいつでも、このことを第一に考えることを忘れてはいけないということです。

値

安定性、スピード、メンテナーの3つをコア・バリューとしています。(SSM)

安定性

ベロシティは非常に重要ですが、GitLabは今やエンタープライズグレードのプラットフォームであり、どんなに小さなMVCであっても安定し、テストされ、優れたアーキテクチャであることが必要だと考えています。たとえMVCであっても、劣化やパフォーマンスの低下、混乱やユーザーの期待を低下させるようなコードをマージすべきではありません。

これは、ユーザーに自分たちのソフトウェアに自信を持ってほしい、そのためにはまずGitLabに自信を持ってもらう必要がある、というCore Valueの延長線上にあります。これは、私たちのソフトウェアに対する私たち自身の信頼が最大であることを意味します。

スピード

ユーザーは GitLab アプリケーションを簡単にナビゲートできなければなりません。これは、ロード時間の速さ、見つけやすいページ、明確なUX、そして摩擦なく目的を達成できるという全体的な感覚を意味します。

さらに、私たちは開発者たちにもスピードを感じてもらい、評価してもらいたいと思っています。つまり、部門全体でより早く成功を達成するためのプロセス、ツール、ドキュメントに多くの努力と考えを注ぐべきなのです。これは、エンジニアとしての私たちだけでなく、質の高い機能をより速いスピードで受け取ることになるユーザーにも利益をもたらします。

メンテナー性

GitLabは今や大規模でエンタープライズグレードのソフトウェアであり、最高の体験を提供するためには複雑なコードが必要になることがよくあります。複雑さは必要なものですが、必要以上に大きくならないように警戒し続けなければなりません。これを最小限に抑えるために、私たちは複雑さをカプセル化することでコードベースをメンテナーにすることに集中したいと思います。これには次のような方法があります：

よく直面する問題を解決するツールを作り、それを簡単に発見できるようにすること。
問題を解決する方法について、より良い文書を書くこと。
コードベースに簡単に追加したり削除したりできるような、疎結合のコンポーネントを書くこと。
私たちがもはや受け入れられないと判断した古い技術やパターンを削除します。

このような側面に焦点を当てることで、エンジニアが複雑さを明確に定義された境界線に収め、素早く仲間と共有できるようにすることを目指しています。

目標

価値観が定義されたので、この価値観に基づいて、GitLabで何を成し遂げたいかを決めていきます。

可能な限り低いFID、LCP、クロスページナビゲーション時間
UIを操作する際のページ再読み込みの最小化
ページあたりのVueアプリケーションをできるだけ少なく
シンプルなページではRuby ViewComponentsを活用し、可能な限りVueのオーバーヘッドを回避します。
VueXからのマイグレーション、ApolloとVueXの併用をやめることが急務です。
コードベースからjQueryを削除
ビジュアルテストフレームワークの追加
CSSバンドルのサイズを最小化
CSSの認知的オーバーヘッドを削減し、メンテナーを改善します。
パイプラインの高速化
ドキュメンテーションを含む、より良い共有コンポーネント・セットの構築

GitLabフロントエンドの将来像については、フロントエンドの目標セクションで詳しく説明しています。

初めての貢献者

初めてマージリクエストを作成するときの注意点や、フロントエンドの変更に関する GitLab のワークフローについての記憶を呼び覚ますために、GitLab の使い始めのページをお読みください。

役立つリンク

取り組み

frontend-initiativeというラベルで、エピックに機能横断的な影響を与える現在のフロントエンドのイニシアチブを見つけることができます。

テスト

フロントエンドのテストの書き方、GitLabテストスイートの実行、テスト関連のイシューのデバッグ方法。

パジャマデザインシステム

パジャマ・デザイン・システムには、再利用可能なコンポーネントと、その技術的および使用ガイドラインが掲載されています。

フロントエンドFAQ

フロントエンドのFAQを読んで、よくある小さなお役立ち情報を確認してください。

国際化 (i18n) と翻訳

フロントエンドの国際化サポートはこのドキュメントで説明されています。ガイドの外部化のパートでは、利用可能なヘルパー/メソッドについて説明します。

トラブルシューティング

フロントエンドの開発で問題が発生しましたか?このガイドをチェックして、イシューの解決に役立ててください。

ブラウザサポート

サポートされているブラウザについては、私たちの要件を参照してください。

BrowserStackを使って、サポートされているブラウザでテストしてください。GitLab共有の1PasswordアカウントのEngineeringvaultに保存された認証情報でBrowserStackにサインインします。