コンテンツにスキップ

ngx_mrubyの開発

人とコーディングエージェントがngx_mrubyを開発する手順です。

Cのモジュールのsrc/、mrbgems/のgem、ビルドを変える前に、AGENTS.mdのDesign principlesを読んでください。そこには、オーナーの決定と、セッションがその決定を当てはめる方法が書いてあります。オーナーの決定は、ワーカーごとに1つのmrb_stateを持つこと、ブロックしないこと、今の性能を保ち、性能を測ることです。当てはめる方法には、どの変更をどう測るかも含まれます。

共有の引き継ぎルールはAGENTS.mdにあります。現在の作業一覧はnextのHANDOFF.md、詳細な検証結果は作業中のPRに記録します。ClaudeやCodexの非公開メモリは補足情報であり、作業を再開するための必須条件ではありません。

  1. AGENTS、関連する計画、コード、テストを読み、続いてHANDOFF、PRの最新本文、レビューコメント、CI結果を確認します。originをfetchし、記録されたbaseとheadが今のものと合うかを確かめてください。日付の付いた記録はその日の状態で、今のブランチの先頭とは限りません。着手する前に、開いているPRと、claude/*やcodex/*を含むすべての作業ブランチを調べます。サイト、ナビゲーション、利用者向けドキュメントの変更では、編集前にSite design acceptanceを読みます。影響する場合は生成される2.xの入口ページも含め、読者がたどる流れ全体を確認します。トップページだけのスクリーンショットでは不十分です。
  2. git worktree list、対象worktreeのブランチ、git status --shortを確認します。可能なら既存の作業用worktreeを使います。前の担当者とローカルのビルド・プレビュープロセスが停止したことを確かめてから引き継ぎます。外部CIは実行中でも構いません。再起動せず状態を確認してください。未コミットの変更は保持します。別の作業にworktreeが必要なら、AGENTSのブランチ規則に従い、適切なbaseから専用の<tool>/<topic>ブランチを作ります。引き継ぎの記録に合わせるために、共有のcheckoutをresetしないでください。
  3. 既存PRを引き継ぐときは、引き継ぐheadをコメントに記します。新規作業では、対象差分がレビューできる状態になったらDraft PRを作り、実装と手元の検査が終わったらReady for reviewにします。AGENTSの「Branches and pull requests」のとおり、DraftではCIを実行せず、Readyへの変更で起動します。Readyは承認ではありません。headや検証結果が変わったらテンプレートの各節を更新し、AGENTSに従ってHANDOFFの作業一覧も更新します。コミットメッセージには問題、判断理由、主なトレードオフ、検証結果を残し、未検証の範囲も明示します。
  4. 停止や引き継ぎの前に、PRへ日付付きの記録を残します。範囲と決定には採用した決定へのリンクと未決事項、状態にはブランチ、head/base、DraftかReadyかとその理由、headのCIの有無、進行段階、残る差分を書きます。根拠にはコマンド、環境とnginxのバージョン、検証したコミット、結果、実行・レビューへのリンク、未完了の作業には未実行、実行中、失敗、拒否、結果不明の操作、次の手順には具体的な操作と前提条件を書きます。どの担当者が作業を止めたかも確認します。まだPRがなければ、通常のドキュメントPRで公開可能な作業範囲と次の手順をHANDOFFに記録します。未完成のファイルはローカルに保持し、生の作業メモは公開しません。後任は、未pushの作業が別のマシンにもあると考えてはいけません。
  5. 一時ログ、スクリーンショット、PRの下書き、個人用の参考資料は、リポジトリの外か、範囲を限定してignoreしたディレクトリに置きます。コミット前にgit status --short --untracked-files=all、git check-ignore -v <generated-path>、git ls-files <generated-path>、git diff --cached --name-statusとgit diff --cachedを確認します。ソース、テスト、公開ドキュメントを隠してはいけません。statusをきれいにするだけのために広いディレクトリをignoreしないでください。リポジトリに入れてはいけないファイルの追加ファイル検査を実行し、公開文面に非公開情報がないか確認します。
  6. 再開時には、実行中のCIと結果不明の操作を確認してから再試行します。ビルド、テストポートの分離、独立レビュー、マージ条件はAGENTSに従います。引き継ぎ記録があっても免除されません。checkoutしたブランチのハーネスを使い、nextのポートオフセット機能が2.xにもあると仮定しないでください。macOSでLinuxのスイート、sanitizer、callgrindを検証するには、.github/workflows/test.ymlと同じパッケージを持つLinuxコンテナを使います。ルートのDockerfileは実行用のイメージで、テストの環境ではありません。

私たちは、ngx_mrubyの開発にvagrantを使っています。

開発するときは、同じ開発環境を使うとよいでしょう。

cd ngx_mruby
vagrant up # run provisioner automatically
vagrant ssh
cd ngx_mruby/
sh test.sh

スクリプトのapply-clang-formatを実行してください。

cd ngx_mruby
sh apply-clang-format

Rubyのコードを持つディレクティブを足す

Section titled “Rubyのコードを持つディレクティブを足す”

ngx_mrubyが後で動かすRubyのコードを持つディレクティブは、各モジュールのヘッダにある表の行です。httpのモジュールはsrc/http/ngx_http_mruby_module.hのNGX_HTTP_MRUBY_CODE_TABLE、streamのモジュールはsrc/stream/ngx_stream_mruby_module.hのNGX_STREAM_MRUBY_CODE_TABLEです。各行には、1つのフックかハンドラの種類について、ファイルのディレクティブと、名前が_codeで終わるインラインのディレクティブと、nginxがそれらを受け付けるコンテキストを書きます。モジュールは、行からコマンドの定義を作ります。HTTPのハンドラの種類では、locationの設定のフィールドcode[kind][form]と、その作成とマージと後始末、フェーズのハンドラとその登録も作ります。この種類のディレクティブを足すときは、表に1行足します。行の種類(HOOK、PHASE、FILTER、SESSION)ごとに何を書き、何が作られるかは、ヘッダにある表のコメントに書いてあります。

postconfigurationは、ある種類と形のフェーズのハンドラと出力フィルタを、設定のディレクティブがそれを使うときだけ加えます。ngx_http_mruby_handler_directiveは、その使用をmainの設定のuses[kind][form]に記録します。フェーズのハンドラを必要とする表の外のディレクティブは、自分でその使用を記録します。たとえば、mruby_add_handler onは、contentのフェーズのファイルの形を記録します。ある種類のフィルタのディレクティブを持たないlocationは、その種類のフィルタのハンドラを、コードと一緒に1つ上のレベルから引き継ぎます(ngx_http_mruby_merge_loc_conf)。

Rubyのコードを持つディレクティブは、すべてsrc/common/ngx_mruby_code.hのngx_mrb_code_setでコードを設定します。この関数は、すでに設定されたフィールドを"NAME" directive is duplicatedで断ります。そのため、1つのコンテキストでは、フックとハンドラの種類ごとにディレクティブを1つだけ書けます。1つのフィールドを共有するファイルの形とインラインの形は、1つと数えます。表に入らないディレクティブは、モジュールの中に個別に書いてあります。SSLのハンドシェイクのハンドラとmruby_server_context_handler_codeは、同じ関数を呼びます。1つのlocationに何個でも書けるmruby_setとmruby_set_codeと、コードを残さないmruby_stream_server_context_codeは、この関数を呼びません。

この節は、Nginx::Async.sleep、Nginx::Async::HTTP.sub_request、Nginx::Stream::Async.sleepを支えるコードを説明します。src/common/ngx_mruby_fiber.c、src/http/ngx_http_mruby_async.c、src/stream/ngx_stream_mruby_async.cか、これらを呼ぶハンドラを変えるときに読んでください。スクリプトから見える動きは、ブロックせずに待つのページと、リファレンスのNginx::Asyncにあります。

ハンドラは、実行のたびにコードを新しいmrubyのファイバーで動かし、そのファイバーのレコードを確保します。HTTPではリクエストのプールから確保し(ngx_http_mrb_fiber_t)、サブリクエストはメインのリクエストのプールを使います。streamでは、セッションの接続のプールから確保します(ngx_stream_mrb_fiber_t)。どちらのレコードも、プロトコルに依らない部分であるsrc/common/ngx_mruby_fiber.hのngx_mrb_fiber_tで始まります。この部分には、ファイバー、mrb_state、GCのルートの保持の中のファイバーのスロット(src/http/ngx_http_mruby_gc_roots.h)、状態、1つのタイマーのイベントがあります。このタイマーは、sleepを呼ぶたびにセットし直します。

  • HTTPのレコードには、ほかにハンドラの種類、sleepの再開のデータ、wakeで使うpostされたリクエストのエントリ、コードが設定した結果、Nginx.redirectのローカルのURI、sub_requestが返したNginx::Async::HTTP::Responseがあります。サブリクエストのレスポンスのステータス、ヘッダ、ボディは、親のリクエストのモジュールのコンテキスト(sub_response_*)に置き、このレコードの中には置きません。
  • モジュールのコンテキストのctx->fiber_procは、いま動いている実行のレコードを指します。ctx->wait(HTTP)とctx->sleeping(stream)は、nginxがハンドラをもう一度呼ぶのを待つレコードを指します。
  • コードのRProcは、コードをコンパイルするときか読み込むときに1回だけ用意します(ngx_mrb_fiber_prepare_proc)。実行のたびには変えません。用意するのはsrc/common/ngx_mruby_code.cのngx_mrb_code_compileとngx_mrb_code_reloadで、どちらもRProcを、mrb_stateがある間GCのルートの保持のスロットに入れておきます。cacheを付けないハンドラのファイルを読み直すと、新しいRProcを同じスロットに入れます。前のRProcを実行中のファイバーは、そのRProcをGCから守ります。

レコードの状態は次のとおりです。

  • RUNNING:ファイバーを作ったときか再開したときの状態です。ファイバーがyieldするとWAITING、返るとDONE、例外を出すとFAILEDになります。
  • WAITING:コードがタイマーをセットするかサブリクエストをpostして、yieldしたときの状態です。タイマーが切れるかサブリクエストが終わるとREADYになり、所有者が終わるとCANCELLEDになります。
  • READY:wakeがレコードに付ける状態です。ハンドラがファイバーを再開するとRUNNINGになり、所有者が終わるとCANCELLEDになります。
  • DONEとFAILED:ファイバーが終わったときの状態で、このときスロットを解放します。レコードは、プールが解放されるまでこの状態のままです。
  • CANCELLED:レコードがWAITINGかREADYのときに、所有者のフックが動いた後の状態です。ファイバーを再開しないので、ensure節を含め、コードの残りの部分は、どれも動きません。
  • リクエストかセッションがレコードを持ちます。レコードは、ファイバーのスロットとタイマーを持ちます。
  • レコードが初めて待つとき、待ちをセットする前に、コードは所有者のフックを足します。HTTPではリクエストのクリーンアップで、nginxはこれをメインのリクエストに置きます。streamでは接続のプールのクリーンアップです。同じときに、postされたリクエストのエントリを確保し(HTTP)、スロットを取ります(ngx_mrb_fiber_hold)。失敗したときはRubyのコードで例外を出し、何もセットしません。待たない実行は、スロットを取らず、所有者のクリーンアップも足しません。
  • 所有者のフックはngx_mrb_fiber_cancelを呼びます。この関数は、解放したプールの上でタイマーが切れないように、残っているタイマーを消します。次にスロットを解放し(HTTPではsub_requestのレスポンスのスロットも解放します)、WAITINGかREADYのレコードをCANCELLEDにします。
  • スロットは1回だけ解放します。解放するのは、ファイバーが普通に終わるか例外で終わったときか、所有者のフックが動いたときのどちらかです。

ngx_mrb_fiber_resumeは、ファイバーを始めるか再開し、ファイバーが待つか、返ったか、例外を出したかを返します。ほかのmrubyの呼び出しが動いているとき(mrb->jmpがセットされているとき)は、mrb_protect_errorを通して再開します。レコードがDONE、FAILED、CANCELLEDのときは、ファイバーに触れずに断ります。ファイバーが例外を出したときは、そのリクエストかセッションのために例外を1回だけログに書き、返る前にmrb->excを消します。ワーカーのすべてのリクエストがmrb_stateを共有するためです。コードが動く間、呼び出し側は、リクエストかセッションの実行コンテキストをpushし、終わったら前のコンテキストに戻します。実行コンテキストは、src/common/ngx_mruby_exec.hのngx_mrb_exec_tで、stateのmrb->udからたどります。HTTPではngx_mrb_runとngx_http_mrb_resume_setが、streamではngx_stream_mruby_handlerがpushします。プロトコルの部分であるngx_mrb_run_fiberとngx_stream_mrb_run_fiberは、ctx->fiber_procを設定します。HTTPのngx_mrb_run_fiberは、ファイバーが動く間、ハンドラの種類とファイバーのレコードを持つコンテキストもpushします。サブリクエストのレスポンスは、ファイバーのFiber.yieldの値として渡します。Rubyのメソッドはngx_mrb_exec_requireでコンテキストを読み、メソッドが動かないハンドラでは例外を出します。どのメソッドがどのハンドラで動くかは、docs/class_and_method/README.mdの「Where the methods work」にあります。

httpモジュールとstreamモジュールのmrb_stateのmrb->udは、ngx_mrubyのものです。stateがある間、mrb->udは実行コンテキストのholderを指します。そのため、mrb->udに自分のポインタを置くmrbgemは、ビルドに加えられません。2.xでこうなっていたのは、streamモジュールのstateだけでした。httpモジュールは、SSLのハンドシェイクのハンドラとserver contextのコードが動く間だけ、mrb->udを設定していました。pushしたコンテキストは、pushした関数のCのスタックにあります。ngx_mrb_runは、ほかのmrubyの呼び出しの中で動くときはngx_mrb_exec_runを通して動きます。ngx_mrb_exec_runは、そこで割り当てが失敗したときも、コンテキストを元に戻します。決まりはsrc/common/ngx_mruby_exec.hにあります。ローカルのURIを渡したNginx.redirectがmruby_setのハンドラ、logハンドラ、フィルタで例外を出すようになったので、ngx_mrubyがほかのmrubyの呼び出しの中でハンドラを動かすことはありません。設計はdocs/proposals/core-alpha1.mdの2.9節に書いてあります。

  • Nginx::Async.sleepはレコードのタイマーをセットします。Nginx::Async::HTTP.sub_requestは、メモリの中で動くサブリクエストをpostし、そのpostハンドラはngx_mrb_async_http_sub_request_doneです。その後、コードはyieldします。logハンドラとフィルタでは、両方ともRuntimeErrorを出します。mruby_setのハンドラでは、nginxがサブリクエストを待たないので、sub_requestもRuntimeErrorを出し、サブリクエストを始めません。
  • ハンドラはNGX_DONEを返し、リクエストのwriteイベントのハンドラをngx_http_mrb_wait_handlerにします(ngx_http_mrb_fiber_wait_on_nginx)。このハンドラは、レコードがWAITINGの間はイベントを無視します。contentフェーズのチェッカーはNGX_DONEごとに参照を1つ外すので、contentハンドラは先に参照を1つ取ります(r->main->count++)。
  • wakeはレコードをREADYにします。タイマーのときは、ngx_http_mrb_fiber_wakeがレコードに持つエントリでリクエストをpostし、接続のpostされたリクエストを処理します。サブリクエストのときは、postハンドラが最初の呼び出しでレスポンスをコピーします。どの呼び出しでも、ngx_http_auth_request_doneと同じように、nginxのrcを変えずに返します。その後、nginxが親のリクエストを自分で起こします。
  • ngx_http_mrb_wait_handlerはREADYを見ると、writeイベントのハンドラをngx_http_core_run_phasesに戻し、フェーズを進めます。r->phase_handlerは動いていないので、チェッカーは同じmrubyのハンドラを呼びます。ngx_http_mrb_fiber_call_againは、コードを始めずにファイバーを再開します。ハンドラは、待たなかったハンドラと同じように、コードの結果をngx_mrb_finalize_rputsを通してチェッカーへそのまま返します。
  • レコードがWAITINGの間にnginxがハンドラを呼ぶと、ハンドラはもう一度NGX_DONEを返し、コードは始まりません。contentハンドラは、このときも参照を1つ取ります。レコードがCANCELLEDなら、ハンドラはNGX_ERRORを返します。
  • mruby_setのハンドラは、rewriteモジュールのスクリプトの中で動きます。このスクリプトは呼ばれるたびに最初のディレクティブから始まるので、nginxはこのハンドラをもう一度呼びません。代わりにwaitハンドラからngx_http_mrb_resume_setがファイバーを再開し、値を変数に入れ、r->phase_handlerを次のハンドラへ進めてフェーズを進めます。例外が出たときと、変数に値を入れられないときは、リクエストを500で終えます。rewriteモジュールのハンドラは既に返っていて、リクエストを終えるフェーズのチェッカーが残っていないためです。
  • どの待ちも、wakeとそのフェーズのチェッカーで終わります。タイマーやpostハンドラがファイバーを再開することはありません。ほかのハンドラのRubyの呼び出しの中で動くハンドラと、内部リダイレクトがモジュールのコンテキストを置き換えたハンドラでは、nginxがハンドラをもう一度呼べません。そこでは、Nginx::Async.sleepとNginx::Async::HTTP.sub_requestがRuntimeErrorを出します。前者は、外側の実行コンテキストが自分のレコードを持っていることで見分けます。ローカルのURIを渡したNginx.redirectがフェーズのハンドラの外では例外を出すので、ngx_mrubyがこのどちらかを起こすことはありません。この確認は、すべての待ちをwakeの経路に保つためのものです。

HTTP:ハンドラの結果とNginx.redirect

Section titled “HTTP:ハンドラの結果とNginx.redirect”
  • Nginx.return、Nginx.send_header、Nginx.status_code=、URLを渡したNginx.redirectは、動いているファイバーのレコードに結果を保存し(ngx_http_mrb_fiber_set_result)、HTTPのステータスはr->headers_out.statusにも保存します。ngx_mrb_finalize_rputsはレコードの結果を読みます。そのため、結果を設定しないハンドラには、前のハンドラが何を保存していても結果がありません。例外は、動いている間に内部リダイレクトがモジュールのコンテキストを置き換えたハンドラです。このハンドラは、自分の結果が無ければ、リダイレクト先が保存したステータスを返します。
  • post_read、server rewrite、rewrite、access、contentのハンドラでは、ローカルのURIを渡したNginx.redirectがURIをレコードに保存します(ngx_http_mrb_fiber_defer_redirect)。ハンドラが終わると、ngx_mrb_run_requestがハンドラの出力を捨て、呼び出しの後にコードが出力を書くかステータスを設定していればwarnのレベルで1行書きます。その後、ngx_http_internal_redirectを呼び、contentフェーズ以外では、取った参照をngx_http_finalize_request(r, NGX_DONE)で外し、NGX_DONEを返します。この呼び出しの中でリクエストが解放されることがあるので、その後はリクエストのものを何も使いません。mruby_setのハンドラ、logハンドラ、ヘッダフィルタ、ボディフィルタでは、フェーズのハンドラのマスクを渡したngx_mrb_exec_requireで、呼び出しがRuntimeError(Nginx.redirect with a local URI is not available in ...)を出し、リダイレクトをしません。リクエストのハンドラが、ほかのハンドラのRubyの呼び出しの中で動くことはありません。docs/proposals/core-alpha1.mdの決定1です。
  • セッションの1つのmrubyのハンドラは、accessフェーズで動きます。Nginx::Stream::Async.sleepはレコードのタイマーをセットしてctx->sleepingを設定し、ハンドラはNGX_DONEを返します。コードが待つ間、接続のreadのハンドラはngx_stream_session_handlerです。listen ... proxy_protocolでは、このハンドラがPROXYのヘッダを読むハンドラにコードの再開まで代わり、readイベントでフェーズが進むようにしています。
  • タイマーはレコードをREADYにして、セッションのフェーズを進めます。accessフェーズのチェッカーがハンドラをもう一度呼び、ngx_stream_mrb_fiber_call_againがファイバーを再開します。ハンドラは、Nginx::Stream::Connection.stream_statusの値を、待たなかったハンドラと同じようにチェッカーへ返します。
  • レコードがWAITINGの間にnginxがハンドラを呼ぶと、ハンドラはNGX_DONEを返し、コードは始まりません。UDPのセッションのデータグラムや、TCPのセッションのクライアントからのバイトがこれに当たり、バイトはコードの後のフェーズのために残ります。バイトを読むまでreadイベントを知らせ続けるイベントの方式(select、poll)では、ハンドラはコードの再開までreadイベントを消します。
  • c->closeがセットされた接続では、WAITINGのレコードを取り消します。nginxは、worker_shutdown_timeoutが切れたときにc->closeをセットします。ハンドラはshutdown timeoutをinfoのレベルでログに書き、NGX_STREAM_OKを返すので、セッションが終わります。
  • クライアントが接続を閉じたとき。HTTP/1.xでは、フェーズが進む間nginxはクライアントから読まないので(ngx_http_block_reading)、待ちは続き、コードは再開します。nginxは、レスポンスを書けないときにリクエストを終えます。TCPのstreamのセッションでは、readイベントでハンドラが動き、読まずにNGX_DONEを返すので、待ちは続きます。閉じたことは、コードの再開の後に分かります。UDPのセッションには、閉じる操作がありません。
  • リロードかSIGQUITのとき。古いワーカーは、HTTPとstreamの待ちを最後まで進めます。待ちのタイマーはキャンセルできないので、ワーカーはそれらのタイマーが切れるまで待ちます。
  • worker_shutdown_timeoutが切れたとき。HTTPでは、nginxがリクエストを打ち切ります。そのクリーンアップで所有者のフックが動き、タイマーを消してレコードを取り消します。streamでは、上に書いたとおり、ハンドラが待ちを取り消してセッションをその場で終えます。
  • SIGTERMのとき。HTTPでもstreamでもフックは動きません。サイクルのプールのクリーンアップでmrb_closeが動き、ファイバーを解放します。

HTTP/2とHTTP/3は、まだどのテストでも確かめていません。ハーネスにそのクライアントがないためです。

このモデルを確かめるケースは、test/t/cases/のasync_resume_result.rb、async_result_isolation.rb、async_subrequest_return.rb、async_set_var.rb、redirect_async.rb、redirect_nested.rb、stream_async_sleep_udp_once.rb、stream_proxy_protocol_wait.rb、workers.rbです。設定はtest/conf/conf.d/にあり、workers.rbの設定はtest/conf/workers/にあります。async_resume_result.rbは、フェーズごとに待つ場合と待たない場合の終わりを比べます。async_result_isolation.rbは、ハンドラの結果がそのハンドラのものであることを確かめます。workers.rbは、リロードとworker_shutdown_timeoutを確かめます。soakのビルド(-DNGX_MRUBY_DEBUG_STATS)では、Nginx::Debug.statsが4つの値を返します。HTTP(timers)とstream(stream_timers)の残っているタイマー、スロットを持つstreamのファイバー(stream_fibers)、GCのルートの保持の中のファイバー(gc_root_fibers)です。test/soak/soak.rbは、timersとgc_root_fibersがサンプルの間で変わらないことを確かめ、stream_timersとstream_fibersについては、値があることだけを確かめます。

新しいバージョンのnginxをサポートする

Section titled “新しいバージョンのnginxをサポートする”

nginx_versionと.travis.ymlを編集します。例はコミット02ddb38です。

TODO:古いバージョンのnginxへの対応を終える方針は、まだ書いていません。

このリポジトリのツリーにあるmrubyを最新のバージョンに更新するには、スクリプトのupdate-mruby-subtreeを使えます。このスクリプトは、mrubyのupstreamのリポジトリをdep-mrubyとして加え、すべての変更を、現在のブランチへpullします。

git checkout -b BRANCH
sh update-mruby-subtree

特定のコミットに更新するときは、refを指定できます。

sh update-mruby-subtree REF

このスクリプトはgit subtree pull --prefix=mruby --squash dep-mruby REFを実行します。そのため、マージは、mruby/の履歴にある最後のsubtreeのsquashから始まります。そのsquashが古いときや、subtreeのpullでないコミットがmruby/を変えていたときは、pullはmruby/の下のコンフリクトで止まります。コンフリクトを手で解決しないでください。mruby/の下のファイルは、決して手で編集しません。代わりに、止まったマージの中で、次のコマンドでsubtreeをrefのツリーと同じ内容に置き換え、マージをコミットします。

git rm -r -q --cached mruby
rm -rf mruby
git read-tree --prefix=mruby/ -u REF^{tree}

タグをローカルのタグとしてfetchしていないときは、ここではREFにコミットのidを使ってください。update-mruby-subtreeは、refをFETCH_HEADにだけfetchします。git read-treeは、ツリーのすべてのファイルを書きます。このリポジトリの.gitignoreがgit addから外すファイルも書きます。たとえば、mruby/Makefileと、mruby/lib/mruby/build/の下のファイルです。コミットする前に、インデックスのmruby/の下にrefのツリーがあることを確かめてください。次の2つのコマンドは、同じidを出力しなければなりません。

git write-tree --prefix=mruby/
git rev-parse REF^{tree}

それから、マージをコミットし、2つのidをコミットメッセージに書いてください。

git commit

コミットの後は、git rev-parse HEAD:mrubyも同じidを出力します。

git subtreeが作ったsquashのコミットは、マージの2つ目の親です。このコミットはgit-subtree-split: <commit of REF>を記録するので、次の更新は、古いsquashではなく、このコミットからマージします。マージは、mruby/の外を何も含めずに、単独でコミットしてください。ビルドの変更は、その後に続くコミットでします。

mruby 4.1以降のコンパイラはPrismを使い、mrubyのツリーにはmrbgems/mruby-compiler/lib/prismがgit submoduleとして含まれます。subtreeのマージで入るのはそのgitlinkだけなので、マージ直後のmruby/にはPrismのソースがなく、ビルドはgit submodule update --init lib/prismで止まります。マージコミットの直後にvendor-mruby-prismを実行し、その結果だけをコミットしてください。

sh vendor-mruby-prism
git commit

スクリプトはHEADのgitlinkからruby/prismのコミットを読み、そのコミットをfetchします。そのコミットのファイルのうち、mruby-compilerのビルドが読むファイルでgitlinkを置き換え、stageします。対象はsrc/、include/、config.yml、templates/template.rbと、それがレンダリングするファイルのテンプレート、LICENSE.mdです。stageした各ファイルのblobが取得したコミットと一致しなければ停止します。コミットメッセージにruby/prismのコミットを記してください。別のコミットを取り込むには、sh vendor-mruby-prism COMMITのように引数で指定します。

次にupdate-mruby-subtreeを実行すると、mruby側にgitlinkがある場所に、このリポジトリでは取り込んだファイルがあります。新しいrefが同じruby/prismのコミットを指すなら、マージはファイルを保持します。異なるコミットなら、一方ではgitlink、他方ではファイルが変更されるため、そのパスでコンフリクトすることがあります。どちらの場合も、先ほどのgit read-treeの手順でマージを完了し、mruby/をgitlinkを含むrefのツリーと一致させてから、再びvendor-mruby-prismを実行します。

build_config.rbのNGX_MRUBY_CORE_GEMSは、ngx_mrubyがビルドするmrubyのコアのgemを、名前で挙げます。そのため、mrubyを更新しただけでは、ビルドするコアのgemは変わりません。一覧のgemが新しいmruby/mrbgemsに無いと、mrubyのビルドは止まります。そのgemを一覧から消すか置き換えるかは、別の決定として決めてください。更新の作業中にビルドを続けるには、NGX_MRUBY_ALLOW_MISSING_CORE_GEMS=1を設定します。ビルドは、無いgemを、通知を出して読み飛ばします。新しいmrubyが加えたgemは、一覧に加えるまでビルドしません。

更新の後は、mruby/buildを消してsh test.shでビルドし、rakeが更新とともに書いたbuild_config.rb.lockをコミットしてください。ロックは、mrubyのバージョンを記録します。rakeはビルドの最後にロックを書きます。一方、NGX_MRUBY_CORE_GEMSのチェックは、rakeがbuild_config.rbを読み込む間にビルドを止めます。そのため、一覧のすべてのgemが見つかるか、NGX_MRUBY_ALLOW_MISSING_CORE_GEMS=1を設定するまで、rakeは新しいロックを書きません。新しいmrubyが自分のgemとして持つようになった依存先は、もうクローンしません。しかし、rakeはロックにそのエントリーを残すので、そのエントリーを消してください。詳しくは、インストールのページの「gemのコミットとbuild_config.rb.lock」に書いてあります。

このリポジトリのツリーにあるngx_devel_kitを最新のバージョンに更新するには、スクリプトのupdate-devkit-subtreeを使えます。このスクリプトは、ngx_devel_kitのupstreamのリポジトリをdep-ngx_devel_kitとして加え、すべての変更を今のブランチへpullします。

git checkout -b BRANCH
sh update-devkit-subtree

特定のコミットに更新するときは、refを指定できます。

sh update-devkit-subtree REF

v3を昇格するまでは、masterが2.xの系列です。v3はnextで開発し、v2.xはmasterを自動でコピーしたブランチです。masterへのpushのたびに、ワークフローのmirror-v2x.ymlが、v2.xをmasterへfast-forwardします。昇格では、v3.0.0の時点でnextをmasterへマージします。こうすると、masterは3.xの系列になり、v2.xが2.xの系列を引き継ぎます。詳しくはBranch strategyにあります。この節は、昇格の手順です。

エージェントがプルリクエストを用意し、チェックを実行し、オーナーの許可の後に、リリースとそのタグを公開します。AGENTS.mdに書いてあります。下の手順では、昇格を始める許可と、手順2と3のリポジトリの設定も、オーナーに任せています。これらは推奨です。下の「決まっていないこと」を見てください。

2026-10-04の時点で、リポジトリにはルールセットが4つあります。手順3は、そのうち最初の2つを変えます。

  • protected-linesは、masterとnextに掛かります。変更は、プルリクエストを通してだけ入ります。ci-okのチェックが通らなければなりません。削除とforce pushはできません。
  • v2x-mirrorは、v2.xに掛かります。削除とforce pushはできません。プルリクエストのルールはありません。そのルールがあると、ミラーのワークフローのpushが拒まれるからです。
  • release-tagsは、v*のタグに掛かります。タグを作り、動かし、消せるのは、リポジトリの管理者だけです。
  • no-branch-shaped-tagsは、v*.x、next、master、mainのタグに掛かります。だれもこれらのタグを作れません。そのため、v2.xのような名前は、いつもブランチを指します。

手順1の前に、オーナーは次のすべてが成り立つことを確かめ、昇格を始める許可を出します。

  1. nextにv3.0.0-rc.Nのプレリリースのタグを付けてあります。そのタグでCIが通り、そのタグに対して報告された不具合のうち、リリースを止めるものはありません。最後のリリース候補をどれだけの期間公開しておくかは、決まっていません。下の「決まっていないこと」を見てください。
  2. v3の移行ガイドと、v3.0.0のリリースノートが完成しています。
  3. 昇格する前に出す2.xの最後のリリースには、masterでタグを付けてあります。そのリリースノートのエントリーも記録してあります。そのタグの後にマージした2.xの修正は、v2.xから出す次の2.xのリリースに入ります。
  4. 下の決まっていないことを決め、v3の計画かこの節に記録してあります。手順4では、昇格した後のブランチの状態を説明します。その説明は、nextが何になるか、修正が系列の間をどう移るか、サイトがどのバージョンを表示するかによって変わります。
  1. 最後にmasterをnextへマージします。エージェントの作業です。ほかのmasterからnextへのマージと同じく、プルリクエストでmasterをnextへマージします。こうすると、nextにすべての2.xの修正が入ります。ここから手順5まで、masterへはほかに何もマージしません。2.xの修正が待てないときは、手順2の前にその修正をマージし、この手順を繰り返します。

  2. ミラーを止めます。オーナーの作業です。v2.xとmasterが同じコミットを指すことを確かめます。このとき、git ls-remote origin refs/heads/master refs/heads/v2.xは、1つのidを2回出力します。idが違うときは、gh workflow run mirror-v2x.yml --ref masterで、masterでワークフローを実行します。gh run list --workflow=mirror-v2x.ymlで実行が終わるまで待ち、もう一度確かめます。実行が失敗したときは、そのジョブのログにv2.xの直し方が書いてあります。たとえば、masterに無いコミットがv2.xにあるときや、workflowsの権限が無いためにpushが拒まれたときです。idが一致するまで、ワークフローを無効にしないでください。一致したら、gh workflow disable mirror-v2x.ymlで無効にします。これ以降、v2.xは2.xの最後のコミットに留まります。この手順は、手順5の前にしてください。手順5で作るマージコミットの最初の親はv2.xの先頭なので、そのpushでワークフローが動くと、v2.xが3.xへfast-forwardされます。手順4は手順5のマージコミットからワークフローのファイルを消すので、それでもワークフローは動きません。ここで無効にすると、手順4に頼らずに、v2.xを守れます。

  3. ほかの系列と同じようにv2.xを保護します。オーナーの作業です。protected-linesの対象にrefs/heads/v2.xを加え、v2x-mirrorを消します。それ以降、v2.xは、ci-okが通ったプルリクエストを通してだけ変わります。CIを変える必要はありません。test.ymlは、既にv*.xへのpushとプルリクエストで動きます。

  4. nextを準備します。エージェントの作業です。nextへの2つのプルリクエストを、次の順番にマージします。

    • 1つ目のプルリクエストは、.github/workflows/mirror-v2x.ymlを消し、昇格の後のブランチを説明します。説明するのは、README.mdのブランチの運用、AGENTS.mdのブランチのテーブルとルール、SECURITY.mdのサポートするバージョン、.github/PULL_REQUEST_TEMPLATE.mdの「Target branch」です。2.xの修正はv2.xを対象にし、v3の修正はmasterを対象にします。README.mdのバッジは、画像のbranch=nextとリンクのquery=branch%3Anextを、masterへ変えます。このプルリクエストは、.github/dependabot.ymlに、target-branch: "v2.x"を持つ2つ目のgithub-actionsのエントリーも加えます。こうすると、手順5からは、masterのこのファイルにそのエントリーがあります。Dependabotはこのファイルをデフォルトブランチからだけ読み、target-branchの無いエントリーではデフォルトブランチだけを更新します。そのため、新しいエントリーが無いと、2.xをサポートする間、v2.xのワークフローでSHAに固定したactionが更新されません。このプルリクエストではサイトも系列に合わせて移します。未リリースの3.1が現行版として表示されないようにするためです。サイトの計画の5.2節に従い、.github/workflows/site.ymlをmasterで実行してmasterからデプロイするようにし、/v2/をv2.xのdocs/からビルドするようにします。site-v2.ymlとsite-dispatch.ymlの2つのファイルは削除します。
    • 2つ目は、docs/releases/v3.0.0.mdについての、「タグの前に」のチェックのプルリクエストです。その節がnextについて書くとおり、範囲は最後のv3.0.0-rc.Nのタグから始まります。このプルリクエストは、そのタグの後にmasterをnextへマージしたことで入った2.xのプルリクエストに、2.xのファイルのエントリーがあることを確かめます。そのマージには、手順1のマージも含まれます。また、タグがまだ無い2.xのリリースについて、そのエントリーをv3.0.0.mdへコピーします。それらは、条件3で書いた2.xの最後のリリースより後にマージした、2.xの修正のエントリーです。v3.0.0がそれらの修正を最初に出すので、コピーします。このプルリクエストの後は、手順5まで、nextブランチへほかに何もマージしません。
  5. 昇格します。エージェントの作業で、その日にオーナーが許可を出してから始めます。headがnextでベースがmasterのプルリクエストを作ります。ほかのすべてのプルリクエストと同じく、AGENTS.mdの「Review and merge」の条件が成り立ったときに、マージコミットでマージします。ただし、マージするのは、手順6のリリースをすぐに出す許可を、オーナーがその日に出した後だけです。こうすると、masterがタグの無い3.xの系列になる時間がありません。手順1でmasterをnextへマージしたので、このプルリクエストにコンフリクトはありません。masterはデフォルトブランチのままです。デフォルトブランチについては、何も変わりません。マージ直前に、オーナーはgithub-pages環境のデプロイブランチ規則をnextからmasterへ変更します。GitHubのSettings、Environments、github-pages、Deployment branchesで設定します。こうすると、マージのpushで、サイトがmasterからデプロイされます。

  6. タグを付けてリリースします。エージェントの作業で、オーナーの許可を得て、手順5の直後にします。手順5のマージコミットでv3.0.0のGitHubのリリースを、リリースノートとともに公開します。gh release createがタグを作ります。リリースには、プレリリースの印を付けません。チェックのプルリクエストのマージコミットではなくこのコミットでリリースを公開するのは、「タグの前に」にある「後のコミット」の場合です。チェックのプルリクエストの後にマージしたプルリクエストについて、チェックを繰り返します。そのようなプルリクエストは手順5の昇格だけで、エントリーは要りません。手順1の後はmasterがnextの祖先なので、手順5で作るマージコミットのツリーはnextと同じです。そのため、設定、スクリプト、ビルドから見えるものは何も変わりません。

  7. 告知します。エージェントの作業です。masterへのプルリクエストで、v3.0.0をリリースした日と、その12か月後に2.xのサポートが終わる日を、README.mdとSECURITY.mdに加えます。v2.xへのプルリクエストでは、次のことをします。

    • v2.xのREADME.md、AGENTS.md、SECURITY.md、プルリクエストのテンプレートで、v2.xを2.xの系列として説明します。
    • v2.xにあるmirror-v2x.ymlのコピーを消します。このワークフローを起動するのはmasterへのpushだけなので、そのコピーは動きません。
    • v2.xのファイルにあるmasterへの絶対のリンクを、v2.xへ向けます。v2.xでは、これらのリンクの先が3.xのファイルになるからです。対象は、このリポジトリのtree/masterとblob/masterのURL、README.mdにあるCIのバッジのbadge.svg?branch=master、docs/install/README.mdにあるダウンロードのリンクのarchive/master.zipです。URLは、2026-10-04の時点で、README.md、docs/、プルリクエストのテンプレートに24個あります。
    • docs/install/README.md、Dockerfile、misc/provision.shにある、デフォルトブランチのクローンに-b v2.xを加えます。対象は、-bの無いgit clone https://github.com/matsumotory/ngx_mruby.gitです。これが無いと、v2.xのインストールガイドに従った2.xの利用者も、v2.xのチェックアウトからDockerfileをビルドした利用者も、3.xを得ます。
    • masterでだけ実行するsite-v2.ymlとsite-dispatch.ymlのコピーをv2.x向けに変え、dispatchでsite.ymlを--ref masterで起動するようにします。こうすると、2.xのドキュメントを変えたときも、/v2/に反映されます。

    リンク、バッジ、クローンは、次のコマンドで一覧できます。git grep -n -E 'ngx_mruby/(tree|blob|archive)/master|branch=master|clone https://github\.com/matsumotory/ngx_mruby'。

  8. 昇格の後の運用です。2.xの修正はv2.xを対象にし、v3の修正はmasterを対象にします。2.xの各リリースは、リポジトリの最新のリリースにならないように公開します。最新のリリースは3.xのままにします。コマンドはgh release create <tag> --latest=falseです。REST APIでは、公開したリリースのmake_latestのデフォルトはtrueです。Webのフォームでは、「Set as latest release」を選ばないでください。

v3の計画は、次のことをまだ決めていません。どれにも推奨があります。条件4は、手順1の前にこれらを決めることを求めています。

  • 昇格の後にnextが何になるか。推奨:次のマイナーリリースの3.1を開発するブランチとして残し、プレリリースのタグを付けます。こうすると、masterは、デフォルトブランチの利用者がビルドする、リリースした3.xの系列のままになります。今のmasterが、リリースした2.xの系列であるのと同じです。もう1つの選択肢は、nextをやめて、3.1をmasterで開発することです。
  • v3.0.0の前に、最後のリリース候補をどれだけの期間公開しておくか。推奨:リリースを止める新しい報告が無いまま、少なくとも2週間公開しておきます。
  • 昇格の後、両方の系列に要る修正をどう移すか。推奨:先にmasterを直し、その修正をbackport/v2.x/<topic>のブランチでv2.xへバックポートします。この名前は、AGENTS.mdが既にバックポートに付けている名前です。v2.xをmasterへマージすると、2.xのためだけの変更も入ります。
  • 昇格の許可を出し、手順2と3でリポジトリの設定を変えるのはだれか。推奨:オーナーです。条件1が成り立つかは判断です。手順6のリリースの許可はオーナーが出し、設定には管理者の権限が要ります。設定を誤ると、v2.xが3.xへ動くおそれがあります。AGENTS.mdは、昇格の許可とリポジトリの設定をまだ扱っていません。

昇格後にサイトが表示するバージョンは、nextのdocs/proposals/site.mdの7節、Q1とQ4で決まっています。オーナーが2026-10-15に決定しました。ngx.mruby.orgは、nextの.github/workflows/site.ymlがdocs/からビルドし、GitHub Actionsでデプロイします。現在はプレフィックスなしのパスにnextの3.x、/v2/にmasterの2.xを表示します。昇格後は、プレフィックスなしのパスにmasterのリリース済み3.x、/v2/にv2.xの2.xを表示します。手順4、5、7でワークフローとデプロイブランチ規則を移します。