Development workflow

The day-to-day cycle: clone, branch, code, test, commit, PR.

Clone and configure

git clone https://github.com/nginx/nginx.git
cd nginx
git remote add fork git@github.com:<you>/nginx.git

Most contributors work on a fork and submit PRs against nginx/nginx:master.

Branch

git checkout -b proxy-fix-keepalive-leak master

Branch names are not strictly conventional; pick something short and descriptive. The PR template doesn't reference branch name.

Build incrementally

After the first auto/configure ..., subsequent edits only need make:

make -j$(nproc)

auto/configure regenerates objs/Makefile and objs/ngx_auto_config.h; rerun it only when you change which modules are enabled or change a probe in auto/.

For a debug build:

auto/configure --with-debug --with-cc-opt='-O0 -g' --with-http_ssl_module --with-http_v2_module --with-http_v3_module --with-stream
make -j$(nproc)

Test locally

The test suite lives in a sibling repo. Clone it once, then point it at your built binary:

git clone https://github.com/nginx/nginx-tests.git ../nginx-tests
cd ../nginx-tests
TEST_NGINX_BINARY=$(realpath ../nginx/objs/nginx) prove -j8 .

Run a specific test:

TEST_NGINX_BINARY=$(realpath ../nginx/objs/nginx) prove -v http_proxy.t

Tests are Perl. See testing for what's available.

Commit hygiene

Each commit should be:

• Self-contained: builds and passes tests on its own
• Single-purpose: one logical change, even if that means several commits in a PR
• Subject ≤ 72 chars, imperative mood, prefixed by area:

HTTP/3: avoid unnecessary header table bloat.

When the encoder...

Common prefixes (see commit history):

Prefix	Use
Core:	Anything in src/core/
Event:	Event loop, OpenSSL bindings
HTTP/2:	src/http/v2/
HTTP/3:	src/http/v3/
QUIC:	src/event/quic/
Upstream:	ngx_http_upstream*, upstream load balancers
Stream:	src/stream/
Mail:	src/mail/
SSL:	ngx_event_openssl*
Configure:	auto/
Win32:	src/os/win32/
GH:	GitHub-side configuration (.github/)

Body lines wrap at 72 chars, separated from the subject by one blank line. End with Closes: https://github.com/nginx/nginx/issues/NNN if applicable.

The commit-message linter is .github/scripts/commit-msg-check.pl. The whitespace check is git log --check.

Send the PR

Open against nginx/nginx:master from your fork's branch. The PR template (.github/pull_request_template.md) wants:

• A short Problem description
• Your Solution approach
• How you Tested it (manual / nginx-tests)
• A Closes: #NNN if it fixes an issue
• A brief Release Notes entry if user-visible

The CLA bot will comment on first-time PRs from contributors who haven't signed the F5 CLA. Sign-by-comment, then push or wait for re-check.

Rebase, don't merge

When master moves under you:

git fetch origin
git rebase origin/master
git push --force-with-lease fork proxy-fix-keepalive-leak

Merge commits in PRs are rejected by the workflow. Squash the trivial fixups inside your PR locally and force-push.

After review

Reviewers comment inline on GitHub. After addressing feedback, force-push the rebased branch. The maintainers will land approved PRs as a fast-forward — you'll see your commits appear directly on master.