コード変更を行うためのステップバイステップガイド
これは何ですか?
これは、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 もインストールする必要があります。最新バージョンの Visual Studio Code は次のページからダウンロードできます:
最後に、Git と SSH の認証情報をマシンに正しく設定しておく必要があります。コンピューターで SSH アクセスを設定していない場合は、次のチュートリアルで説明されている設定を完了してください:
ステップバイステップガイド
Visual Studio Code から
gitlabフォルダを開きます。File > Open… に移動し、gitlab-development-kitまたは同等の GDK ディレクトリ内のgitlabフォルダを見つけることで開けます。ターミナルを開きます。すべての主要なオペレーティングシステムでターミナルまたは CLI が利用できます。このガイドは MacOS で作成されたため、すべての例でターミナルを使用します。MacOS のターミナルは Applications フォルダで見つかります。
ターミナルで
gitlabフォルダに移動します。cdコマンドを使用してフォルダに入っていきます。gitlabフォルダに素早くジャンプする簡単な方法の 1 つは、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 テキストの変更に焦点を当てるため、その性質の例を残りのガイドで使用します。このガイドでは、一般設定で見つけられるテキスト、特に「Naming, Topics, Avatar」セクションのテキストを変更します。
テキストは
Update your project name, topics, description and avatar.です。これをUpdate your project name, topics, description, compliance framework, and avatar.に変更します。これはチュートリアル用の例にすぎず、実際の変更は永続的にプッシュされません。この特定のテキストが GDK で動作する環境に存在することを確認してください。サンプルプロジェクトのいずれかに移動して、Settings をクリックし、次に General をクリックすることで確認できます。最初のセクションのヘルパーテキストが、変更するものです。
何を変更するかが明確になったので、この変更が起こるために変更する必要があるファイルを見つける時間です。これを行うには、Visual Studio Code に移動し、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ファイルが再生成されます。このジョブは数分かかる場合があり、ターミナルはすぐにフィードバックを返さないので、辛抱強く待ってください。changelog を追加する: changelog は、変更が何をしているかの簡単な説明です。changelog は、ターミナルから次のコマンドで起動できる対話型のコマンドプロンプトで生成されます:
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。このコマンドは upstream ブランチを作成し、そのリモートブランチに対して変更をプッシュします。プッシュが完了すると、ターミナルは MR の URL を表示し、それをブラウザで開いて変更を完了できます。
- ターミナルに次の git コマンドを入力します:
完了です! マイルストーンとタイプラベルを含む、最終的な詳細をすべて MR に追加してください。
注意点
テストに紐付いた文字列
上記の例は、テストを持たないテキスト文字列のプロセスを示しています。多くの UI 文字列は特定のテストに紐付いていない（したがって spec ファイルの変更は不要）一方、UI テキストをチェックするテストアサーションも存在します。通常、これらのテストは要素の内部テキストを読むことで特定の UI コンポーネントの存在を検証しています。
テストに紐付いた UI 文字列を変更し、spec ファイルのテキストを変更しないと、文字列を見つけられなくなるためテストが失敗します。
変更しているテキストがテストに紐付いているかは、VS Code の検索結果でも .spec.js または .spec.rb ファイル内に表示されているかで確認できます。
一般的に、テストが通るには spec ファイル内で古いテキストを新しいテキストに置き換えるだけで済みます。ただし、テキストの置き換えに spec ファイルへの追加変更が必要となる少数のケースがありますが、それは稀です。
一般的な文字列を見つける
上記の例は、非常に特定的なテキスト文字列のプロセスを示しています。非常に特定的な文字列は、アプリ全体でそのテキストのインスタンスが 1 つしかない可能性が高いため、簡単に見つけて特定できます。しかし、たとえばボタン内のテキスト「Expand」のような一般的な文字列はどうでしょうか?
一般的な文字列を置き換える必要がある場合、正しいファイルとテキストのインスタンスを特定するために論理的な思考を行う必要があるかもしれません。
良い戦略の 1 つは、一般的な文字列の近くにある非常に特定的なテキスト文字列を見つけることです。その特定的な文字列を検索すると、他のテキストを含むテンプレートやコンポーネントファイル内で見つかる可能性が高いです。そのファイルを見つけたら、CMD + F を押してファイルにスコープ指定して検索し、そのファイル内で一般的な文字列を検索できます。そのファイル内の結果は、変更しようとしているテキストへの正しい参照である可能性が最も高いです。ただし、変更が実際に反映されているかは、ライブ GDK 環境を確認することで常に確認してください。
bfd74782)