Developing ngx_mruby
Development procedures for human contributors and coding agents.
Before you change the C module (src/), the gems in mrbgems/ or the
build, read Design principles in
AGENTS.md: the owner’s decisions (one mrb_state per worker, no blocking,
keep the existing performance and measure it) and how sessions apply them,
including which changes are measured and how.
Continuing shared work
Section titled “Continuing shared work”AGENTS.md defines the shared handoff rules.
The current queue is HANDOFF.md on next; the active PR holds
the detailed evidence. Claude’s and Codex’s private memories are optional
context, not prerequisites for continuing work.
- Read AGENTS, the relevant plan, code and tests, then HANDOFF and the PR’s
latest body, review comments and CI results. Fetch
originand verify the recorded base and head; a dated snapshot is not a live branch tip. Search open PRs and all topic branches, includingclaude/*andcodex/*, before starting a queue item. For site, navigation or user-facing documentation work, read Site design acceptance before editing. Follow its complete reader journey, including generated 2.x entry pages when affected; a homepage-only screenshot is not sufficient. - Inspect
git worktree list, the intended worktree’s branch andgit status --short. Reuse the existing task worktree when possible. Confirm that its previous writer and local build/preview processes have stopped before taking over; external CI may continue and should be inspected rather than restarted. Preserve uncommitted work. If another task needs a worktree, create its own<tool>/<topic>branch from the appropriate base under the branch rules in AGENTS. Do not reset a shared checkout to make its files match a handoff. - Claim an existing PR with a comment naming the head being taken over. For new work, open a PR as a draft once the scoped changes are reviewable, and mark it ready for review when the work and its local checks are done (“Branches and pull requests” in AGENTS: a draft runs no CI, ready starts it, and ready is not approval). Keep its template sections current as the head or evidence changes; update the queue through HANDOFF as AGENTS requires. Use commit messages to preserve the problem, reasoning, relevant tradeoffs and validation, with explicit limits when something was not tested.
- Before stopping or transferring work, put a dated checkpoint in that PR: scope and decisions (link the accepted decision, distinguish open questions); state (branch, head/base, draft or ready and why, whether a CI run of the head exists, stage and remaining diff); evidence (commands, environment/nginx version, tested commits, results and run/review links); unfinished work (not run, in progress, failed, denied or uncertain outcomes); next step (the concrete action and its prerequisite). Confirm which writer has stopped. If there is no PR yet, record the public scope and next step in HANDOFF via the normal documentation PR; preserve unfinished files locally without publishing raw scratch data. A successor must not assume unpushed work is available on another machine.
- Keep temporary logs, screenshots, PR drafts and personal references
outside the repository or in narrowly ignored directories. Before each
commit inspect
git status --short --untracked-files=all,git check-ignore -v <generated-path>,git ls-files <generated-path>, andgit diff --cached --name-status/git diff --cached. Source, tests and public documentation must remain visible; never hide a broad directory merely to make status clean. Run the added-file check in Files that do not belong in the repository and review public text for private material. Public and private work records state intent, rationale, constraints and decisions without conversation quotations or attribution as justification. Public records omit private conversations, message identifiers and personal environment details. Keep adopted decisions distinct from proposals. - On resumption, check running CI and any operation with an uncertain
outcome before retrying. Follow AGENTS for builds, test-port isolation,
independent review and merge gates; a checkpoint does not waive them.
Use the harness of the checked-out branch: do not assume the port-offset
support on
nextexists on 2.x. On macOS, use a Linux container for the Linux suite, sanitizer, valgrind and callgrind evidence, with the docker forms of docs/test/README.md and of “Before a tag” in AGENTS.md. They build against the OpenSSL of Ubuntu 22.04, where the cells of .github/workflows/test.yml build OpenSSL from source (3.5.9 onnext, 1.1.1w on 2.x), and on 2.x they skip the auto-ssl case, which the cells run (“valgrind in CI” in docs/test/README.md of each branch). The root Dockerfile is a runtime image, not that test environment.
Recommended development environment
Section titled “Recommended development environment”We use vagrant for development of ngx_mruby.
You may want to develop in same development environment.
Setup development environment
Section titled “Setup development environment”cd ngx_mrubyvagrant up # run provisioner automaticallyvagrant sshTest in development environment using ubuntu 18.04
Section titled “Test in development environment using ubuntu 18.04”cd ngx_mruby/sh test.shFormat C source code
Section titled “Format C source code”Run apply-clang-format script.
cd ngx_mrubysh apply-clang-formatAdding a directive with Ruby code
Section titled “Adding a directive with Ruby code”The directives whose Ruby code ngx_mruby keeps for later are the rows of a
table in the header of each module: NGX_HTTP_MRUBY_CODE_TABLE in
src/http/ngx_http_mruby_module.h and NGX_STREAM_MRUBY_CODE_TABLE in
src/stream/ngx_stream_mruby_module.h. Each row names the file directive
and the inline directive (the one whose name ends in _code) of one hook or
handler kind, and the contexts where nginx accepts them. The module makes
from the rows the command entries, and for an HTTP handler kind also its
fields in the location configuration (code[kind][form]), their create,
merge and cleanup, the phase handlers and their registration. A new
directive of such a kind is one row; its comment in the header says what
each kind of row (HOOK, PHASE, FILTER, SESSION) gives and makes.
Postconfiguration adds the phase handler of a kind and form, and the
output filters, only when a directive of the configuration uses them:
ngx_http_mruby_handler_directive records the use in uses[kind][form]
of the main configuration, and a directive outside the table that needs a
phase handler records it itself, as mruby_add_handler on does for the
file form of the content phase. A location without a filter directive of
a kind takes the filter handler of that kind, with its code, from the
level above it (ngx_http_mruby_merge_loc_conf).
Every directive with Ruby code sets its code with ngx_mrb_code_set
(src/common/ngx_mruby_code.h): it refuses a field that is already set
with "NAME" directive is duplicated, so a hook or handler kind takes one
directive in a context, and the file and the inline form that share a
field count as one. The directives that the tables do not cover are
written out in the module: the SSL handshake handler and
mruby_server_context_handler_code call the same function;
mruby_set and mruby_set_code, which a location may have many of, and
mruby_stream_server_context_code, which keeps no code, do not.
How a handler waits: the record of its fiber
Section titled “How a handler waits: the record of its fiber”This section describes the code behind Nginx::Async.sleep,
Nginx::Async::HTTP.sub_request and Nginx::Stream::Async.sleep, for a
change to src/common/ngx_mruby_fiber.c, src/http/ngx_http_mruby_async.c,
src/stream/ngx_stream_mruby_async.c or the handlers that call them. What
a script sees is in Waiting without blocking and in
the reference of Nginx::
The record
Section titled “The record”Each run of a handler runs its code in a new mruby fiber, and allocates a
record for it: from the request pool in HTTP (ngx_http_mrb_fiber_t; a
subrequest uses the pool of its main request), and from the connection
pool of the session in stream (ngx_stream_mrb_fiber_t). Both begin with
the part that does not depend on the protocol, ngx_mrb_fiber_t in
src/common/ngx_mruby_fiber.h: the fiber, the mrb_state, the slot of the
fiber in the GC root holder (src/http/ngx_http_mruby_gc_roots.h), the
state, and one timer event, which each sleep arms again.
- The HTTP record also holds the handler kind, the data of the resume of
a sleep, the entry of the posted request of the wake, the result that the
code set, the local URI of
Nginx.redirect, and theNginx::Async::HTTP::Responsethatsub_requestreturned. The status, the headers and the body of the subrequest’s response are in the module context of the parent request (sub_response_*). ctx->fiber_procof the module context points at the record of the current run.ctx->wait(HTTP) andctx->sleeping(stream) point at a record that waits for nginx to call its handler again.- The
RProcof the code is prepared once, when the code is compiled or loaded (ngx_mrb_fiber_prepare_proc), not on every run.ngx_mrb_code_compileandngx_mrb_code_reloadinsrc/common/ngx_mruby_code.cdo it, and keep theRProcin a slot of the GC root holder for the life of themrb_state. A reload of a handler file withoutcacheputs the newRProcin the same slot; a fiber that still runs the previous one keeps it alive.
The states of a record:
RUNNING: the fiber was created or resumed. It becomesWAITINGwhen the fiber yields,DONEwhen it returns andFAILEDwhen it raises.WAITING: the code armed a timer or posted a subrequest and yielded. It becomesREADYwhen the timer fires or the subrequest ends, andCANCELLEDwhen the owner ends.READY: the wake marked the record. It becomesRUNNINGwhen the handler resumes the fiber, andCANCELLEDwhen the owner ends.DONEandFAILED: the fiber ended, and its slot is freed. The record stays in this state until its pool is freed.CANCELLED: the owner hook ran while the record wasWAITINGorREADY. The fiber is not resumed, so the rest of its code, anensureclause included, does not run.
Who owns what
Section titled “Who owns what”- The request or the session owns the record, and the record owns its slot and its timer.
- At the first wait of a record, before the wait is armed, the code adds
the owner hook (a request cleanup in HTTP, which nginx keeps on the main
request; a connection pool cleanup in stream), allocates the entry of the
posted request (HTTP), and takes the slot (
ngx_mrb_fiber_hold). A failure raises in the Ruby code with nothing armed. A run that never waits takes no slot and adds no cleanup. - The owner hook calls
ngx_mrb_fiber_cancel: it deletes a pending timer, so that no timer fires on a freed pool, frees the slot (in HTTP also the slot of the response ofsub_request), and marks aWAITINGorREADYrecordCANCELLED. - The slot is freed when the fiber ends, normally or with an exception, or by the owner hook, once.
The resume
Section titled “The resume”ngx_mrb_fiber_resume starts or resumes the fiber, through
mrb_protect_error when another mruby call runs (mrb->jmp is set), and
returns whether the fiber waits, returned, or raised. It refuses a record
that is DONE, FAILED or CANCELLED without touching its fiber. When
the fiber raised, it logs the exception once, for its request or session,
and clears mrb->exc before it returns, because all requests of the worker
share the mrb_state. The callers push the execution context of the
request or session (ngx_mrb_exec_t of src/common/ngx_mruby_exec.h,
which mrb->ud of the state reaches) for the time the code runs, and put
back the previous one afterwards: in HTTP ngx_mrb_run and
ngx_http_mrb_resume_set, in stream
ngx_stream_mruby_handler. The protocol parts, ngx_mrb_run_fiber and
ngx_stream_mrb_run_fiber, set ctx->fiber_proc; in HTTP,
ngx_mrb_run_fiber also pushes a context with the handler kind and the
record of the fiber for the time the fiber runs, and passes the response of
a subrequest as the value of its Fiber.yield. The Ruby methods read the
context with ngx_mrb_exec_require, which raises where the method does not
work (“Where the methods work” in docs/class_and_method/README.md).
mrb->ud of the mrb_state of the http module and of the stream module
belongs to ngx_mruby: it points at the holder of the execution context for
the life of the state. An mrbgem that puts a pointer of its own in mrb->ud
cannot be added to the build. On 2.x only the state of the stream module was
like that; the http module set mrb->ud only while the SSL handshake
handler or the server context code ran. The context of a push lives on the C
stack of the function that pushed it: ngx_mrb_run goes through
ngx_mrb_exec_run when it runs inside another mruby call, which puts the
context back also when an allocation fails there (the rule is in
src/common/ngx_mruby_exec.h). ngx_mruby runs no handler inside another
mruby call since Nginx.redirect with a local URI raises in mruby_set
handlers, log handlers and filters (section 2.9 of
docs/proposals/core-alpha1.md).
HTTP: a wait and its end
Section titled “HTTP: a wait and its end”Nginx::Async.sleeparms the timer of the record, andNginx::Async::HTTP.sub_requestposts an in-memory subrequest whose post handler isngx_mrb_async_http_sub_request_done; then the code yields. Both raise aRuntimeErrorin a log handler or a filter, andsub_requestalso in anmruby_sethandler, because nginx does not wait for that subrequest.- The handler returns
NGX_DONEand sets the write event handler of the request tongx_http_mrb_wait_handler, which ignores events while the record isWAITING(ngx_http_mrb_fiber_wait_on_nginx). A content handler first takes a reference to the request (r->main->count++), because the content checker drops one for eachNGX_DONE. - The wake marks the record
READY. For the timer,ngx_http_mrb_fiber_wakealso posts the request with the entry kept in the record and runs the posted requests of the connection. For a subrequest, the first call of the post handler copies the response, and every call returns nginx’srcunchanged, asngx_http_auth_request_donedoes; nginx then wakes the parent. ngx_http_mrb_wait_handlerseesREADY, sets the write event handler back tongx_http_core_run_phasesand runs the phases.r->phase_handlerdid not move, so the checker calls the same mruby handler, andngx_http_mrb_fiber_call_againresumes the fiber instead of starting the code. The handler then returns the result of the code to the checker throughngx_mrb_finalize_rputs, as a handler that did not wait does.- nginx calling the handler while its record is
WAITINGgetsNGX_DONEagain (a content handler takes another reference), and the code does not start again. A record that isCANCELLEDmakes the handler returnNGX_ERROR. - An
mruby_sethandler runs inside the script of the rewrite module, which starts the script from its first directive on each call, so nginx does not call it again.ngx_http_mrb_resume_set, from the wait handler, resumes the fiber, assigns the value to the variable, movesr->phase_handlerto the next handler and runs the phases. After an exception, or when the variable cannot get the value, it finalizes the request with 500, since no phase checker is left to end it: the rewrite module’s handler returned already. - Every wait ends through the wake and the checker of its phase: no timer
and no post handler resumes a fiber.
Nginx::Async.sleepandNginx::Async::HTTP.sub_requestraise aRuntimeErrorin a handler that runs inside the Ruby call of another handler (an outer execution context has a record of its own) and in a handler whose module context an internal redirect replaced, where nginx could not call the handler again. ngx_mruby makes neither happen sinceNginx.redirectwith a local URI raises outside the phase handlers (below); the check keeps every wait on the path of the wake.
HTTP: the result of a handler and Nginx.redirect
Section titled “HTTP: the result of a handler and Nginx.redirect”Nginx.return,Nginx.send_header,Nginx.status_code=andNginx.redirectwith a URL store the result in the record of the fiber that runs (ngx_http_mrb_fiber_set_result), and an HTTP status also inr->headers_out.status.ngx_mrb_finalize_rputsreads the result of the record, so a handler that sets none has no result, whatever an earlier handler of the request stored. The exception is a handler whose module context an internal redirect replaced during its run: without a result of its own, it returns the status that the target stored.- The first three also store the status as the code gave it in the record
(
ngx_http_mrb_fiber_set_status;Nginx.redirectwith a URL resets it to 0).ngx_mrb_run_requestpasses it from the record of the handler that ends tongx_mrb_finalize_rputs(the record is per run of a handler, and an rputs chain that an earlier handler left in the module context does not carry it), which sends the output with that status when no status was set after the output, so a status set before the output applies to it (decision 6 of docs/proposals/core-alpha1.md). The result can differ from it: before any output,Nginx.return Nginx::HTTP_OKin a handler other than a content handler of the main request sets the result 500, and output that follows still goes out with 200. Nginx.redirectwith a local URI, in a post_read, server rewrite, rewrite, access or content handler, keeps the URI in the record (ngx_http_mrb_fiber_defer_redirect). When the handler has ended,ngx_mrb_run_requestdrops its output, logs a line at thewarnlevel when the code wrote output or set a status after the call, callsngx_http_internal_redirect, drops the reference that it took withngx_http_finalize_request(r, NGX_DONE)in every phase but content, and returnsNGX_DONE. The request can be freed in that call, so nothing of it is used afterwards. Inmruby_sethandlers, log handlers and header and body filters, the call raises aRuntimeError(Nginx.redirect with a local URI is not available in ...) throughngx_mrb_exec_requirewith the mask of the phase handlers, and makes no redirect: no handler of a request runs inside the Ruby call of another one (decision 1 of docs/proposals/core-alpha1.md).
Stream: a wait and its end
Section titled “Stream: a wait and its end”- The one mruby handler of a session runs in the access phase.
Nginx::Stream::Async.sleeparms the timer of the record and setsctx->sleeping, and the handler returnsNGX_DONE. While the code waits, the read handler of the connection isngx_stream_session_handler: on alisten ... proxy_protocolit replaces the reader of the PROXY header until the code resumes, so that a read event runs the phases. - The timer marks the record
READYand runs the phases of the session. The access checker calls the handler again, andngx_stream_mrb_fiber_call_againresumes the fiber; the handler returnsNginx::Stream::Connection.stream_status, as a handler that did not wait does. - nginx calling the handler while its record is
WAITING(a datagram of a UDP session, bytes from the client of a TCP session) getsNGX_DONE, and the code does not start again; the bytes stay for the phase after the code. With the event methods that report a read event until the bytes are read (select,poll), the handler deletes the read event until the code resumes. - A
WAITINGrecord of a connection withc->closeset (nginx sets it whenworker_shutdown_timeoutexpires) is cancelled: the handler logsshutdown timeoutat theinfolevel and returnsNGX_STREAM_OK, so the session ends.
What ends a wait from outside
Section titled “What ends a wait from outside”- The client closes the connection. HTTP/1.x: nginx does not read from the
client while the phases run (
ngx_http_block_reading), so the wait goes on and the code resumes; nginx ends the request when it cannot write the response. A TCP stream session: the read event runs the handler, which returnsNGX_DONEwithout reading, so the wait goes on, and the close is seen after the code resumes. A UDP session has no close. - A reload or SIGQUIT. The old worker finishes the waits of HTTP and of stream: their timers are not cancelable, so the worker waits for them.
worker_shutdown_timeoutexpires. HTTP: nginx terminates the request, and its cleanup runs the owner hook, which deletes the timer and cancels the record. Stream: the handler cancels the wait and ends the session, as above.- SIGTERM. No hook runs, in HTTP or in stream;
mrb_closein the cleanup of the cycle pool frees the fibers.
No test covers HTTP/2 or HTTP/3 yet: the harness has no client for them.
Tests and counters
Section titled “Tests and counters”The cases that pin this model are in test/t/cases/:
async_resume_result.rb (the same end with and without a wait, per
phase), async_result_isolation.rb (the result of a handler is its own),
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 and
workers.rb (reloads and worker_shutdown_timeout). Their configuration
is in test/conf/conf.d/, and that of workers.rb in test/conf/workers/. The soak build
(-DNGX_MRUBY_DEBUG_STATS) reports in Nginx::Debug.stats the pending
timers of HTTP (timers) and of stream (stream_timers), the stream
fibers that hold a slot (stream_fibers), and the fibers in the GC root
holders (gc_root_fibers). test/soak/soak.rb keeps timers and
gc_root_fibers the same from sample to sample, and checks only that
stream_timers and stream_fibers are reported.
Adding newer version nginx support
Section titled “Adding newer version nginx support”Edit nginx_version and .travis.yml. See https://github.com/matsumotory/ngx_mruby/commit/02ddb38b68702d9abe8fb0a8c172ee1d80ad2b2d for example.
TODO: retirement policy
Updating mruby
Section titled “Updating mruby”If you want to update in-tree mruby to latest version, you can use update-mruby-subtree script. It adds the mruby upstream repo as dep-mruby and pull all changes to the current branch.
git checkout -b BRANCHsh update-mruby-subtreeIf you want to update to a specific commit, you can specify a ref.
sh update-mruby-subtree REFThe script runs git subtree pull --prefix=mruby --squash dep-mruby REF, so
the merge starts from the last subtree squash in the history of mruby/.
When that squash is old, or when mruby/ was changed by commits that were
not subtree pulls, the pull stops with conflicts under mruby/. Do not
resolve them by hand (files under mruby/ are never edited by hand).
Instead, inside the merge that stopped, replace the subtree with the exact
tree of the ref, and commit the merge:
git rm -r -q --cached mrubyrm -rf mrubygit read-tree --prefix=mruby/ -u REF^{tree}Use the commit id for REF here if the tag was not fetched as a local tag;
update-mruby-subtree fetches the ref only into FETCH_HEAD. git read-tree
writes every file of the tree, also the ones that .gitignore of this
repository would keep out of a git add (for example mruby/Makefile and
files under mruby/lib/mruby/build/). Before you commit, check that the
index holds the tree of the ref under mruby/; the two commands must print
the same id:
git write-tree --prefix=mruby/git rev-parse REF^{tree}Then commit the merge, and put the two ids in the commit message:
git commitAfter the commit, git rev-parse HEAD:mruby prints the same id.
The squash commit that git subtree made is the second parent of the merge
and records git-subtree-split: <commit of REF>, so the next update merges
from that commit instead of the older squash. Commit the merge alone, with
nothing outside mruby/, and make the build changes in the commits that
follow.
Since mruby 4.1, the mruby compiler is built on
Prism, and the tree of mruby has
mrbgems/mruby-compiler/lib/prism as a git submodule. The subtree merge
brings only the gitlink of that submodule, so after the merge mruby/ has
no Prism sources, and the mruby build stops at
git submodule update --init lib/prism. Right after the merge commit, run
vendor-mruby-prism and commit its result alone:
sh vendor-mruby-prismgit commitThe script reads the commit of ruby/prism from the gitlink in HEAD,
fetches that commit, replaces the gitlink with the files of that commit
that the build of mruby-compiler reads (src/, include/, config.yml,
templates/template.rb with the templates of the files that it renders,
and LICENSE.md), stages them, and stops unless each staged file is the
same blob as in that commit. Put the commit of ruby/prism in the commit
message. To vendor another commit of ruby/prism, give it as the argument
(sh vendor-mruby-prism COMMIT).
At the next update-mruby-subtree, this repository has files where the
tree of mruby has the gitlink. When the new ref names the same commit of
ruby/prism, the merge keeps the vendored files. When it names another
commit, the merge changes the gitlink on one side and the vendored files on
the other, and can stop with a conflict at that path. In both cases, finish
the merge with the git read-tree steps above, which give mruby/ the
exact tree of the ref with its gitlink, and then run vendor-mruby-prism
again.
NGX_MRUBY_CORE_GEMS in build_config.rb names the mruby
core gems that ngx_mruby builds, so an update does not change them by itself.
The mruby build stops when a listed gem is not in the new mruby/mrbgems:
remove it from the list, or replace it, as a decision of its own. To build
anyway while you work on the update, set NGX_MRUBY_ALLOW_MISSING_CORE_GEMS=1;
the build then skips the missing gems with a notice. Gems that the new mruby
adds are not built until you add them to the list.
After the update, remove mruby/build, build with sh test.sh, and commit the
build_config.rb.lock that rake wrote with the update: the lock records the
version of mruby. rake writes the lock at the end of a build, and the check of
NGX_MRUBY_CORE_GEMS stops the build while rake loads build_config.rb, so
rake writes no new lock until every listed gem is found or
NGX_MRUBY_ALLOW_MISSING_CORE_GEMS=1 is set. A dependency that the new mruby
provides as one of its own gems is no longer cloned, but rake keeps its entry
in the lock, so delete that entry (see “Gem commits” in
docs/install/README.md).
Updating ngx_devel_kit
Section titled “Updating ngx_devel_kit”If you want to update in-tree ngx_
git checkout -b BRANCHsh update-devkit-subtreeIf you want to update to a specific commit, you can specify a ref.
sh update-devkit-subtree REFPromoting v3 to master
Section titled “Promoting v3 to master”Until v3 is promoted, master is the 2.x line, v3 is developed on next, and
v2.x is an automatic copy of master: on every push to master, the
workflow mirror-v2x.yml fast-forwards
v2.x to it. The promotion merges next into master at v3.0.0, so that
master becomes the 3.x line and v2.x keeps the 2.x line (see
Branch strategy). This section is the
procedure.
Agents prepare the pull requests, run the checks and, after the owner’s go-ahead, publish the releases with their tags, as AGENTS.md says. The steps below also give the owner the go for the promotion and the repository settings of steps 2 and 3; those parts are recommendations (see “Open questions” below).
The repository has four rulesets (as of 2026-10-04). Step 3 changes the first two:
protected-lines, onmasterandnext: changes only through pull requests, theci-okcheck must pass, no deletion, no force push.v2x-mirror, onv2.x: no deletion, no force push. It has no pull request rule, because that rule would reject the pushes of the mirror workflow.release-tags, onv*tags: only repository admins create, move or delete them.no-branch-shaped-tags, on the tagsv*.x,next,masterandmain: nobody can create them, so that a name such asv2.xalways means the branch.
Conditions
Section titled “Conditions”The owner checks that all of these hold and gives the go before step 1:
- A
v3.0.0-rc.Npre-release is tagged onnext, CI passed on it, and no defect reported against it blocks the release. How long the last release candidate stays out is open (see “Open questions” below). - The v3 migration guide and the release notes of v3.0.0 are complete.
- The last 2.x release before the promotion is tagged on
master, and the entries of its release notes are recorded. 2.x fixes merged after that tag go out in the next 2.x release fromv2.x. - The open questions below are decided and recorded, in the v3 plan or in
this section. Step 4 describes the branches as they are after the
promotion, and that text depends on what
nextbecomes, how fixes travel between the lines and which version the site shows.
-
Final merge-up (agent). Merge
masterintonextwith a pull request, as for every merge-up, so thatnexthas every 2.x fix. From here until step 5, merge nothing else intomaster. If a 2.x fix cannot wait, merge it before step 2 and repeat this step. -
Stop the mirror (owner). Check that
v2.xandmasterpoint at the same commit:git ls-remote origin refs/heads/master refs/heads/v2.xprints one id twice. If the ids differ, run the workflow onmaster(gh workflow run mirror-v2x.yml --ref master), wait until the run has finished (gh run list --workflow=mirror-v2x.yml), and check again. If the run fails, its job log says how to repairv2.x, for example whenv2.xhas commits that are not onmasteror when the push was rejected for theworkflowspermission. Do not disable the workflow until the ids match. Then disable it withgh workflow disable mirror-v2x.yml. From here on,v2.xstays at the last 2.x commit. Do this before step 5: the merge commit of step 5 has the tip ofv2.xas its first parent, so the workflow, if it ran for that push, would fast-forwardv2.xto 3.x. Step 4 removes the workflow file from the merge commit of step 5, which also keeps it from running; disabling it here protectsv2.xwithout relying on step 4. -
Protect
v2.xlike the other lines (owner). Addrefs/heads/v2.xto the targets ofprotected-linesand deletev2x-mirror. From then on,v2.xchanges only through pull requests that passedci-ok. CI needs no change: test.yml already runs on pushes and pull requests tov*.x. -
Prepare
next(agent). Two pull requests tonext, merged in this order:- A pull request that deletes
.github/workflows/mirror-v2x.ymland describes the branches as they are after the promotion: the branch strategy in README.md, the branch table and rules in AGENTS.md, the supported versions in SECURITY.md, and “Target branch” in.github/PULL_REQUEST_TEMPLATE.md(2.x fixes targetv2.x, v3 fixes targetmaster). It points the badges of README.md atmaster: their images (branch=next) and their links (query=branch%3Anext). It also adds to.github/dependabot.ymla secondgithub-actionsentry withtarget-branch: "v2.x", so that the file has it onmasterfrom step 5 on. Dependabot reads that file only from the default branch, and an entry withouttarget-branchupdates only the default branch, so without the new entry nothing would update the SHA-pinned actions in the workflows ofv2.xwhile 2.x is supported. It also moves the site with the lines, so that pages of an unreleased 3.1 never become the current version (5.2 of the site proposal):.github/workflows/site.ymlruns on and deploys frommasterand builds/v2/fromdocs/ofv2.x, andsite-v2.ymlandsite-dispatch.ymlare removed. - The check pull request of
“Before the tag” for
docs/releases/v3.0.0.md. As that section says fornext, its range starts at the lastv3.0.0-rc.Ntag, it confirms that the 2.x pull requests brought by the merges ofmasterintonextsince that tag (including step 1) have their entries in the 2.x file, and it copies intov3.0.0.mdthe entries of the 2.x release that is not tagged yet (the 2.x fixes merged after the last 2.x release of condition 3), because v3.0.0 ships them first. After this pull request, merge nothing else intonextuntil step 5.
- A pull request that deletes
-
Promote (agent, on the owner’s go that day). A pull request with head
nextand basemaster, merged with a merge commit when the conditions of “Review and merge” in AGENTS.md hold, as for every pull request, and only after the owner has given the go-ahead that day for the release of step 6 right after it, so thatmasteris not an untagged 3.x line in between. It has no conflicts, because step 1 mergedmasterintonext.masterstays the default branch; nothing about the default branch changes. Right before the merge, the owner changes the deployment branch rule of thegithub-pagesenvironment fromnexttomaster(Settings, Environments,github-pages, “Deployment branches”), so that the push of the merge deploys the site frommaster. -
Tag and release (agent, after the owner’s go-ahead), right after step 5. Publish the GitHub release
v3.0.0at the merge commit of step 5 (gh release create, which creates the tag), not marked as a pre-release, with the release notes. Releasing at that commit instead of the merge commit of the check pull request is the “later commit” case of “Before the tag”: the check is repeated for the pull requests merged after the check pull request. The only one is the promotion of step 5, and it needs no entry:masteris an ancestor ofnextafter step 1, so the merge commit of step 5 has the same tree asnextand changes nothing that a configuration, script or build can observe. -
Announce (agent). A pull request to
masterthat adds the release date of v3.0.0 and the end of 2.x support (twelve months later) to README.md and SECURITY.md. A pull request tov2.xthat:- describes
v2.xas the 2.x line in its README.md, AGENTS.md, SECURITY.md and pull request template; - deletes its copy of
mirror-v2x.yml(that copy never runs, because only pushes tomastertrigger it); - points the absolute links to
masterin its files atv2.x, because onv2.xthey would lead to the 3.x files: thetree/masterandblob/masterURLs of this repository (24 on 2026-10-04, in README.md,docs/and the pull request template), the CI badgebadge.svg?branch=masterin README.md and the download linkarchive/master.zipindocs/install/README.md; - adds
-b v2.xto the clones of the default branch (git clone https://github.com/matsumotory/ngx_mruby.gitwithout-b) indocs/install/README.md,Dockerfileandmisc/provision.sh. Without it, a 2.x user who follows the install guide onv2.x, or builds the Dockerfile from av2.xcheckout, gets 3.x; - points its copies of
site-v2.ymlandsite-dispatch.yml, which run only formaster, atv2.x, and makes the dispatch startsite.ymlwith--ref master, so that a change to the 2.x documentation still reaches/v2/.
This command lists the links, the badge and the clones:
git grep -n -E 'ngx_mruby/(tree|blob|archive)/master|branch=master|clone https://github\.com/matsumotory/ngx_mruby'. - describes
-
Afterwards. 2.x fixes target
v2.x, and v3 fixes targetmaster. Each 2.x release is published so that it does not become the repository’s latest release, which stays with 3.x:gh release create <tag> --latest=false. Through the REST API,make_latestdefaults totruefor a published release; in the web form, leave “Set as latest release” unselected.
Open questions
Section titled “Open questions”The v3 plan does not decide these yet. Each has a recommendation. Condition 4 requires them to be decided before step 1.
- What
nextbecomes after the promotion. Recommendation: keep it as the development branch of the next minor release (3.1), with pre-release tags, so thatmasterstays the released 3.x line that users of the default branch build, as it is the released 2.x line today. The other choice is to retirenextand develop 3.1 onmaster. - How long the last release candidate stays out before v3.0.0. Recommendation: at least two weeks without a new report that blocks the release.
- How a fix that both lines need travels after the promotion.
Recommendation: fix
masterfirst and backport the fix tov2.xon abackport/v2.x/<topic>branch, the name AGENTS.md already gives backports. Mergingv2.xintomasterwould also bring changes made only for 2.x. - Who gives the go for the promotion and changes the repository settings
in steps 2 and 3. Recommendation: the owner. Whether condition 1 holds is
a judgment, the go-ahead for the release of step 6 is the owner’s, and
the settings need admin rights; a mistake there lets
v2.xmove to 3.x. AGENTS.md does not cover the go or the repository settings yet.
The site proposal decides which version the site shows after the
promotion (Q1 and Q4, decided by the owner on 2026-10-15, in section 7 of
docs/proposals/site.md
on next). The site, ngx.mruby.org, is built from docs/ by
.github/workflows/site.yml on next and deployed by GitHub Actions:
3.x from next at the unprefixed paths, and
2.x from master under /v2/. From the promotion on, the unprefixed
paths show the released 3.x from master and /v2/ shows 2.x from
v2.x: steps 4, 5 and 7 move the workflows and the deployment branch
rule.