コード変更を行うためのステップバイステップガイド
このガイドについて
これは、GitLab のメインコードベースにコード変更を加えるためのステップバイステップガイドです。テキストの変更など、小さな UI の変更を通じて GitLab に貢献したい、ある程度の技術知識を持つ方が、手順に沿って進められるチュートリアルです。こうした変更は、GitLab の UI の一貫性を高める有意義な貢献になります。
こうした変更は GitLab プロジェクトに価値を加える優れた方法です。また、GitLab のコードベースに慣れ、将来さらに有意義な変更を行いたい方にとって、最初の MR に適しています。
このガイドは、@jj-ramirezによるこちらの動画チュートリアルに基づいています。
前提条件
このガイドを始める前に、GDK がインストールされ、動作していることを確認してください。GDK のインストールとセットアップの手順は、以下のページを参照してください。
注: GDK をインストールすると、gitlab-development-kit フォルダが作成されます（これはデフォルト名で、インストール中に名前を変更した場合は異なることがあります）。その中に、GitLab プロジェクトの全ファイルを含む、動作する gitlab フォルダがあります。GDK を正しくインストールしていれば、両方のフォルダが存在し、中身を確認できるはずです。
このチュートリアルではコードエディターとして Visual Studio Code を使うため、こちらもインストールする必要があります。最新バージョンの Visual Studio Code は、以下のページからダウンロードできます。
最後に、マシン上で Git と SSH の認証情報を正しく設定しておく必要があります。コンピューターで SSH アクセスを設定していない場合は、以下のチュートリアルに従って設定してください。
ステップバイステップガイド
Visual Studio Code で
gitlabフォルダを開きます。「ファイル > 開く…」から、gitlab-development-kitまたはそれに相当する GDK ディレクトリ内のgitlabフォルダを探して開きます。ターミナルを開きます。主要なオペレーティングシステムには、すべてターミナルや CLI が用意されています。このガイドは MacOS で作成したため、すべての例でターミナルを使います。MacOS のターミナルは「アプリケーション」フォルダにあります。
ターミナルで
gitlabフォルダに移動します。cdコマンドでフォルダをたどって移動できます。gitlabフォルダにすばやく移動する簡単な方法として、Finder ウィンドウでフォルダを見つけ、ターミナルにドラッグ & ドロップする方法があります。これにより、gitlabフォルダがある場所の絶対パスを取得できます。まずターミナルに
cdと入力します。Finder ウィンドウでgitlabフォルダを見つけ、ターミナルにドラッグ & ドロップします。コマンドはcd /Users/jj-gitlab/Desktop/GDK/gdk2/gitlabのようになります。Enterを押すと、目的のフォルダに移動できます。ターミナルでマシン名の横にフォルダ名が表示されているかを確認してください。gdk startコマンドを実行して GDK を起動します。GDK のインストール時に設定したテストホストで、ローカル版の GitLab が起動します。通常は、ローカルホストの https://127.0.0.1:3000/ でアクセスできます。正常に動作していれば、ブラウザに GitLab インスタンスのログインページが表示されます。GDK の認証情報を使ってログインしてください。GDK の認証情報は、ターミナルで
gdk helpと入力すると、表示されるメッセージの最下部で確認できます。準備ができたら変更をプッシュできるよう、Git を準備します。まず、新しいブランチを作成して切り替えます。ターミナルで
git switch -c "your-branch-name"コマンドを入力します。ブランチ名には、意味のある短い名前を選んでください。ブランチ名は、ケバブケース（‘a-branch-name’ のようにハイフンで区切る形式）にします。新しいブランチに切り替えたら、変更できそうな箇所を探します。このガイドは主に UI テキストの変更を扱うため、以降はその例を使います。一般設定にある「名前、トピック、アバター」セクションのテキストを変更します。
対象のテキストは
Update your project name, topics, description and avatar.です。これをUpdate your project name, topics, description, compliance framework, and avatar.に変更します。これはチュートリアル用の例であり、実際に変更を恒久的にプッシュするわけではありません。GDK 環境にこのテキストが存在するか、確認してください。サンプルプロジェクトのいずれかで、「設定」、「一般」の順にクリックします。最初のセクションの補足テキストが、今回変更するものです。
変更する内容が明確になったので、変更対象のファイルを探します。Visual Studio Code ウィンドウの左サイドバーにあるグローバル検索アイコンをクリックします。検索クエリを入力するテキストボックスが表示されます。ここでは、
Update your project name, topics, description and avatarという特定の文字列を検索します。この行を検索ボックスにコピー & ペーストしてください。クエリに一致する検索結果がいくつか表示されます。このガイドでは UI 文字列の変更を扱うため、対象テキストが現れる正しい箇所を変更できるよう、一般的なルールをいくつか示します。
gitlab.potファイルは変更しません。これらは翻訳ファイルで、このガイドの後半で実行するジョブによって作成・更新されます。対象の文字列は、
.haml（サーバーテンプレート）ファイルか.vue（フロントエンドコンポーネント）ファイル内にある可能性があります。どちらの場合でも、対象の文字列は_('string')やs_('string')のような Markdown 風の記法で囲まれていることが多いです。この例では、探しているテキストは_('Update your project name, topics, description and avatar.')のようになります。検索クエリはテストファイルにも現れることがあります。テストファイルの末尾は
.spec.rbまたは.spec.jsです。文字列がテストファイルに一致する場合、そのファイルも変更する必要がある可能性があります。テストファイルを変更しないと、変更をプッシュした際にパイプラインが失敗します。この点は、このガイドの 注意点 セクションで詳しく説明します。
UI 文字列を変更する際のルールを確認したので、実際に変更します。前の手順では
Update your project name, topics, description and avatarを検索しました。edit.html.hamlというファイル内に一致する箇所が見つかるはずです。このファイルは前述の条件をすべて満たしています。.hamlファイルであり、一致する文字列は文字列デコレーター_()で囲まれています。一致する箇所が見つかったら、テキストを
Update your project name, topics, description, compliance framework, and avatar.に置き換えてファイルを保存します。ブラウザで実行中の GDK に戻り、ページを更新すると、UI に変更が反映されているはずです。UI の変更が完了したので、MR を作成する前の準備作業を行います。
ターミナルで翻訳ジョブを実行する。文字列の変更を翻訳ファイルに反映する処理です。ターミナルに
bin/rake gettext:regenerateコマンドをコピー & ペーストします。前述のgitlab.potファイルが再生成されます。このジョブには数分かかることがあり、ターミナルからすぐには応答が返らないため、そのまま待ってください。変更履歴を追加する。 変更履歴には、変更内容の簡単な説明を記載します。ターミナルで
bin/changelog 'Your changelog message'コマンドを実行すると、対話形式のコマンドプロンプトが起動し、変更履歴を生成できます。コマンドを入力したら、ターミナルの案内に従ってください。
これで、GitLab のメインリポジトリに対して、この変更の MR を作成する準備ができました。この手順は心配しなくてかまいません。何かを壊すことはなく、MR は後からメインリポジトリに影響を与えずに閉じられます。変更をプッシュするには、次の 2 つを行います。
- ターミナルに、以下の git コマンドを入力します。
git add .。変更したファイルを追加し、コミットできるようにするコマンドです。git commit -m 'A meaningful message'。変更を含むコミットを作成するコマンドです。コミットメッセージのルールに従わないとパイプラインが失敗するため、必ず従ってください。コミットメッセージは 3 単語以上、75 文字以下とし、先頭の文字を大文字にし、末尾にピリオド.を付けないようにします。git push --set-upstream origin your-branch-name。リモートにブランチを作成し、そのブランチに変更をプッシュするコマンドです。プッシュが完了すると、ターミナルに MR の URL が表示されます。ブラウザで開いて、変更を仕上げます。
- ターミナルに、以下の git コマンドを入力します。
完了です! マイルストーンとタイプラベルを含め、必要な詳細をすべて MR に追加してください。
注意点
テストに紐付いた文字列
上記の例では、テストのないテキスト文字列を変更する手順を示しています。多くの UI 文字列は特定のテストに紐付いておらず、spec ファイルを変更する必要はありません。一方、UI テキストを確認するテストのアサーションも存在します。通常、こうしたテストは要素の内部テキストを読み取ることで、特定の UI コンポーネントの存在を確認しています。
テストに紐付いた UI 文字列を変更し、spec ファイルのテキストを変更しないと、文字列が見つからなくなるためテストが失敗します。
変更対象のテキストが、VS Code の検索結果で .spec.js または .spec.rb ファイル内にも現れるかどうかで、テストに紐付いているかを確認できます。
一般的には、spec ファイル内で古いテキストを新しいテキストに置き換えるだけでテストが通ります。ただし、まれに、テキストの置き換えに伴って spec ファイルに追加の変更が必要な場合もあります。
一般的な文字列を見つける
上記の例では、非常に具体的なテキスト文字列を変更する手順を示しています。こうした文字列は、アプリ全体で 1 箇所にしか現れない可能性が高いため、簡単に見つけて特定できます。それでは、ボタンの「展開」のような一般的な文字列の場合はどうでしょうか。
一般的な文字列を置き換える場合は、正しいファイルと該当箇所を特定するために、論理的に考える必要があるかもしれません。
有効な方法の 1 つは、一般的な文字列の近くにある、非常に具体的なテキスト文字列を探すことです。具体的な文字列を検索すると、もう一方のテキストを含むテンプレートやコンポーネントのファイルが見つかる可能性が高くなります。そのファイルが見つかったら、CMD + F を押して検索範囲をそのファイルに絞り、一般的な文字列を検索します。そのファイル内の検索結果は、変更したいテキストを指している可能性が高いです。ただし、実行中の GDK 環境で、変更が実際に反映されているかを必ず確認してください。
5d840611)