Drupal.org へのモジュールプロジェクトの作成と編集

Drupal Advent Calendar 2023 に寄稿した記事です。

はじめに

先日、Theme region wrapper というモジュールを Drupal.org 上に公開しました。モジュールプロジェクトを作る際、日本語の情報を見つけることができなかったので、日本語の記事を書くことにしました。モジュールプロジェクトの作成から、プロジェクト作成後に編集を行う手順を紹介します。

モジュールプロジェクトページ作成

Drupal.org にモジュールプロジェクトページ作成は、標準の Drupal コンテンツ作成と同様の操作を行います。作成手順は以下の通りです。

1. プロジェクト追加ページから Module project を選択する
2. 作成するモジュールプロジェクトの必須項目を入力する
   • 必須項目は下記の6項目
     1. Name
        • Name と Short name は既存のプロジェクトとかぶらない値にする
     2. Project type
        • Project type に Sandbox という値が存在するが将来的に廃止されるため、Full project で作成する
     3. Short name
        • Short name はプロジェクト作成後に変更できないので、慎重に決定する
          
     4. Maintenance status
     5. Development status
        
     6. Issues の Components
        • 何かをリリースするまであまり重要ではないのでそのままで問題ない
          
   • 必須項目ではないが Description はモジュールのページを開いたときの内容になるためリリース前の段階でも何かしら入力しておいたほうが良いと思われる
     • Description には初期値としてテンプレート（内容は後述）が設定されているが、これにそのまま従っているプロジェクトは調べた限り見つからなかったのでテンプレートの内容は参考程度にとどめる。
     • Description 標準の Drupal コンテンツ作成の本文と同様に入力値が自動抜粋され、200文字程度が概要として設定される。概要に記述したい内容を自動抜粋されたくない場合は、抜粋部分の最後に <!--break--> を挟むか、Edit summary をクリックして概要を記述する
3. Save ボタンを押下すると、プロジェクトページが作成される

Description のテンプレートの中身

Here, write an introduction that summarizes the purpose and function of this project with a focus on users brand new to Drupal. Answer the question: What solution does this module provide? The first 200 characters of this will be shown when browsing projects. Alternatively, you can click “Edit summary” above and enter the exact summary you want (it should be 200 characters or less).

<h3 id="module-project--features">Features</h3>
Here, answer the following questions: What is the basic functionality? What unique features does enabling this project add? When and why would someone use this module? What use cases are there?

<h3 id="module-project--post-installation">Post-Installation</h3>
How does this module actually work once I install it? Should I go to a config page? Should I look for a new content type? Should I go and manage my text formats? Provide an overview of the configuration process and any other special considerations for the module.

<h3 id="module-project--additional-requirements">Additional Requirements</h3>
Does this project need anything beyond Drupal core? Include any dependent modules, libraries, APIs, etc., that are required for this project to work.

<h3 id="module-project--recommended-libraries">Recommended modules/libraries</h3>
Are there any projects that enhance or improve the functionality of this project?

<h3 id="module-project--similar-projects">Similar projects</h3>
If there are modules providing similar functionality, please describe what differentiates them.

<h3 id="module-project--support">Supporting this Module</h3>
If you have a Patreon, OpenCollective, etc. you can put links here to describe how people can support development. 

<h3 id="module-project--community-documentation">Community Documentation</h3>
A great place to add links to YouTube walkthroughs, external documentation, or a demo site (use DrupalPod!).

You may continue to put additional information below here, if there are other things you think people need to know about your module!

git.drupalcode.org にあるプロジェクトへのソースコードのコミット

プロジェクトページが作成されると、git.drupalcode.org 上の Gitlab にもプロジェクトが作成されます。このプロジェクトにソースコードをコミットすることでモジュールをダウンロードできる準備が整います。コミットまでの手順は以下の通りです。

1. Drupal.org にログインし、アカウントページ上部 Profile タブのすぐ下にある、Git access をクリックし、Git のユーザ名設定と利用規約同意を行う
2. Gitlab にアクセスできるように Git Authentication for Drupal.org Projects のページに従い、SSH 接続の鍵作成および設定を行う
   • 正しく設定されていれば、ssh -T [e-mail] で Git ユーザ名が返ってくる
3. ローカルにあるプロジェクトのソースコードを設置するディレクトリで Git の初期化をし、リモートブランチ設定のため git remote add origin [e-mail]:project/my_project_short_name.git を実行する
   • ローカルの開発ブランチは 1.0.x にする（main は使用しない）。Drupal のプロジェクトでは Dev 版のリリースをする際に、1.0.x や 1.1.x、2.0.x のような形式のブランチ名でないと有効なブランチ名とみなされないので注意する。
   • https://git.drupalcode.org/ に作成されたプロジェクトを未コミット状態で見ると、Git global setup の中で「"@users.noreply.drupalcode.org"」で終わるメールアドレスを設定する表示が出るが、開発時の普段使いのメールアドレスで問題ない場合は設定しないで良い。
4. ローカルでソースコードをコミットした後、リモートにソースコードを push して Gitlab のプロジェクトに反映する

プロジェクトのリリース

コミットしたソースを Drupal.org のプロジェクトページからダウンロードできるようにするには、プロジェクトページで設定を行う必要があります。
Dev 版とバージョン番号が付くリリースでは下記のような違いがあります。

• Dev 版のリリース
  • リリース対象：ブランチ
  • 有効なブランチ名の例：1.0.x、2.0.x
• バージョン番号が付くリリース（アルファやベータ、安定版など）
  • リリース対象：タグ
  • 有効なタグ名の例：1.0.0-alpha1、1.1.0-beta2、2.0.0

リリース手順

実際のリリース手順は以下の通りです。

1. リリース前に対象となるブランチまたはタグをプロジェクトに用意する
2. Drupal.org にログインした状態で、作成したプロジェクトのページ（例：my_project_short_name なら https://www.drupal.org/project/my_project_short_name）にアクセスし、Edit を押下する
3. プロジェクトの編集画面に遷移したら Edit の下に Project と Releases が表示されるので Releases を押下する
4. Dev 版の場合は対象のブランチ、それ以外の場合は対象のバージョンのタグを選択して Next を押下する
5. リリースノートやリリースの要約を記述する画面に遷移するので、適宜内容を入力して Save を押下する

プロジェクトの編集

Issues の分類を整える

リリースが完了したら、ユーザからの報告を受ける Issues の分類を整えます。Issues の分類を整える手順は以下の通りです。

1. Drupal.org にログインした状態で、作成したプロジェクトのページにアクセスし、Edit を押下する
2. プロジェクトの編集ページ下部にある縦タブの、Issues を押下する
3. Components にプロジェクトに必要な分類を追加・削除、順番の変更を行う
   • もし、Issue 作成時の分類の初期値を設定したり、Issue 投稿のガイドライン、独自の Issue サマリーを設定したい場合は、それぞれ設定する
4. 編集ページ最下部にある Save を押下して、変更を反映する

プロジェクトにサムネイル画像を追加する

プロジェクトにサムネイル画像を追加することで、Drupal 開発者にモジュールの利用シーンを思い描きやすくなるかもしれません。プロジェクトにサムネイル画像を追加する手順は以下の通りです。

1. Issues の分類を整える時と同様、プロジェクトの編集ページを開く
2. Images にある Add a new file から画像ファイルの追加とアップロードを行う
   • サムネイルとして表示されるサイズは最大横220ピクセルに設定される（縦の最大サイズは不明）
   • サムネイルに使用される画像は、Fences モジュールのプロジェクトページを見る限りウェイトが一番小さい画像が使用される
3. 編集ページ最下部にある Save を押下して、変更を反映する

リリースノートの修正をする

リリースノートに Typo があった時など、リリースに関する情報を修正したい場合があります。リリースに関する情報の修正は、プロジェクトの編集とは異なるページから遷移するため注意が必要です。リリースノートを修正する手順は以下の通りです。

1. Drupal.org にログインした状態で、作成したプロジェクトのページにアクセスし、ページ下部にある View all releases を押下する
2. 変更対象のリリースを押下する
3. リリースの詳細ページ上部にある Edit を押下する
4. リリースの編集画面に遷移したら Release notes や Short description を修正してページ下部にある Save を押下する

おわりに

この記事では、Drupal.org 上にモジュールプロジェクトを作成し、作成後に編集を行う手順の紹介をしました。正直なところ、モジュールを作成してメンテナーとして運用を始めたばかりなので簡単な内容しかないですが、時間がたって知見がたまった時に改めて記事を書ければなあと思います。この記事が Drupal.org にモジュールを公開することにしり込みしている人にとって助力となり、少しでも日本発のモジュールが増えてくれれば幸いです。
最後に、プロジェクトを作成してリリースしたら Drupal.org のアカウント情報の Contributor roles に Contributed module, theme, or distribution maintainer を追加するのを忘れないようにしましょう。