Contribution Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
The Zephyr Project is a community-driven open-source project that relies on contributions to maintain its scalable real-time operating system (RTOS). These guidelines establish standards for submitting code, documentation, and features to ensure consistency, security, and quality across the codebase. Contributions are governed by the Apache 2.0 license and require adherence to the Developer Certificate of Origin (DCO) process via Signed-off-by lines in commits. Sources: CONTRIBUTING.rst:1-15, doc/contribute/index.rst:7-13
The following sections detail the technical requirements, organizational roles, and workflow processes required for successful participation in the Zephyr ecosystem.
Project Roles and Governance
Participation in the Zephyr project is organized into defined roles, each with specific rights and responsibilities. This meritocratic structure ensures that those with demonstrated skill and dedication have appropriate influence over the project's direction. Sources: doc/project/project_roles.rst:5-15
Role Definitions
| Role | Description | Key Responsibilities |
|---|---|---|
| Contributor | Anyone contributing code or docs. | Abide by decisions, follow Code of Conduct, respect community rules. |
| Collaborator | Highly involved Contributor. | Review code, ensure quality, mentor new contributors, participate in releases. |
| Maintainer | Lead Collaborators for a specific area. | Set subsystem architecture, enforce Code of Conduct, triage static analysis. |
| Assignee | Subsystem maintainer for a specific PR. | Drive PR to merge, moderate technical disagreements, solicit approvals. |
Sources: doc/project/project_roles.rst:18-120
The following diagram illustrates the progression and relationship between primary project roles:
The diagram shows the hierarchy from Contributor to Maintainer and specialized roles like Release Manager. Sources: doc/project/project_roles.rst:18-160
Pull Request (PR) Requirements
Zephyr encourages small, logical, and self-contained pull requests. Large changes should be preceded by an RFC (Request for Comments) proposal to provide context and define a minimum viable implementation. Sources: doc/contribute/contributor_expectations.rst:7-25, doc/contribute/contributor_expectations.rst:63-75
Technical Standards for Submission
- Commit Units: Each commit must build cleanly and pass CI. Commits should represent clear, logical units of change to maintain bisectability. Sources: doc/contribute/contributor_expectations.rst:53-61, doc/contribute/contributor_expectations.rst:111-118
- Testing: PRs must include tests for new functionality, API behavior contract changes, or hardware-agnostic bug fixes. Sources: doc/contribute/contributor_expectations.rst:31-40
- Documentation: Any functional code change must be accompanied by updates to affected documentation in American English. Sources: doc/contribute/contributor_expectations.rst:142-148
- Doxygen Style: Public APIs must be fully documented using Doxygen. Use
/**for blocks,@paramfor parameters, and@retvalfor return values. Sources: doc/contribute/style/doxygen.rst:13-35
PR Workflow and Escalation
Reviewers and authors use a collaborative process to refine code. If technical disagreements occur, the project follows a defined escalation path. Sources: doc/contribute/contributor_expectations.rst:155-175
This sequence shows the interaction between authors and reviewers, including the escalation to the Architecture Working Group if a resolution cannot be reached locally. Sources: doc/contribute/contributor_expectations.rst:178-208
Secure Coding Principles
All code submitted to Zephyr should comply with established security design principles to minimize the attack surface of the RTOS. Sources: doc/security/secure-coding.rst:18-24
- Economy of Mechanism: Keep designs small and simple to reduce potential vulnerabilities.
- Least Privilege: Threads and programs should operate with the minimum permissions required.
- Fail-safe Defaults: Access should be denied by default and services disabled unless explicitly enabled via Kconfig.
- Input Validation: Use allowlists for input checking rather than blocklists.
- Open Design: Security must not rely on secrecy but on publicly accepted cryptographic algorithms.
Sources: doc/security/secure-coding.rst:47-95, doc/security/secure-coding.rst:104-142
External Component Integration
Zephyr allows the reuse of external source code to avoid re-implementing basic functionality. This is governed by strict merit and licensing reviews. Sources: doc/contribute/external.rst:7-15
Integration Modes
- Main Tree: Imported directly into the
zephyrrepo. Code must be reformatted to Zephyr style and adhere to all project coding guidelines. - Module: Imported as a separate repository managed via
west. Code is developed externally and remains in its original format. - External Tooling: Software assisting compilation or testing (e.g., scripts) that does not link into the final binary.
Sources: doc/contribute/external.rst:62-115
Approval Process for Non-Apache 2.0 Licenses
If an external component uses a license other than Apache 2.0, it requires a specific approval flow:
The flowchart depicts the dual-approval requirement for non-standard licenses involving both the Technical Steering Committee and the Governing Board. Sources: doc/contribute/external.rst:142-178
Release Process and Merge Criteria
Zephyr follows a time-based release cycle (approximately 6 months) consisting of a Development Phase and a Stabilization Phase. Sources: doc/project/release_process.rst:7-18
Merge Criteria for Mainline
To maintain quality, a PR must meet several criteria before being merged into the tree:
- Approvals: Minimum of 2 approvals, including the designated Assignee.
- Four-Eye Principle: For shared code, at least one approval must come from an organization different from the submitter's.
- Review Period: Minimum of 2 business days (4 hours for trivial changes).
- CI Checks: Must pass all automated checks including Kconfig, Devicetree, Coding Style (checkpatch), and integration tests.
Sources: doc/project/release_process.rst:64-105
Conclusion
The Zephyr Contribution Guidelines establish a rigorous framework for community participation, emphasizing small logical changes, mandatory peer review, and secure design principles. By following these processes, contributors ensure that the Zephyr RTOS remains a high-quality, auditable, and secure platform for resource-constrained devices. Sources: doc/contribute/index.rst:7-20, doc/project/release_process.rst:7-12