How to contribute

This section is the practical handbook for working in the nginx codebase: how to pick up work, how to send a change, what's expected at review, and how the maintainers think about quality.

Where work comes from

There are three sources of incoming work:

1. GitHub Issues — tagged bug or enhancement via the issue templates in .github/ISSUE_TEMPLATE/. Triaged by an assigned engineering owner from F5.
2. Mailing list — historically the canonical contribution channel; some long-time contributors still send patches there.
3. F5 internal roadmap — features driven by NGINX Plus customer needs that are also useful to mainline.

Most outside contributions arrive as a GitHub PR against master. The CONTRIBUTING.md file is the authoritative process doc.

What "done" looks like

A change is ready to merge when:

1. It compiles cleanly with auto/configure --with-debug plus the modules it touches, on at least Linux + one BSD (per the project's Tested OS and Platforms policy).
2. The functional test suite (nginx-tests) passes, and new behavior has new tests.
3. Each commit has a tightly scoped subject line, an informative body, and follows the formatting conventions in patterns-and-conventions.
4. The CLA bot (f5_cla.yml) has marked the contributor as having signed the F5 CLA.
5. A maintainer has reviewed and approved.

CI gates

Pull requests run the following GitHub Actions checks (defined in .github/workflows/):

Workflow	What it checks
check-pr.yml	Bookkeeping (PR metadata)
check-commit-message.yaml	Runs commit-msg-check.pl on every commit in the PR
check-whitespace.yaml	git log --check — trailing whitespace, conflict markers
check-version-bump.yaml	Catches accidental version bumps
f5_cla.yml	Enforces the F5 CLA
mark-issues-prs-stale.yaml	Marks long-idle items
new-issue-welcome.yaml	Posts a welcome on first-time issues
buildbot.yml	Triggers an external buildbot for compile + test on real OSes

The actual build/test for cross-platform coverage runs outside of GitHub Actions on F5's buildbot infrastructure; the buildbot.yml workflow is the bridge.

Sub-pages

• Development workflow — clone, branch, commit, PR, rebase
• Testing — running and writing tests in nginx-tests
• Debugging — error_log debug, gdb tips, common pitfalls
• Patterns and conventions — coding style, naming, error handling
• Tooling — auto/configure, make, format checkers, optional tooling

For protocol-level changes, also read systems/configuration (how directives become code) and primitives/module (how modules plug in).