Contribution Guide

Introduction

Refer to documentation at Zephyr Project website for more information on how to configure, install and use Zephyr Project.

Repository layout

To clone the Zephyr Project repository:

git clone https://github.com/zephyrproject-rtos/zephyr

Pull Requests and Issues

You can find open Pull Requests on GitHub here and you can find open issues here.

Contributing

To contribute to Zephyr Project it is helpful to provide as much information as you can about your change, including any updates to documentation (if appropriate), and test... test... test.

• Fork zephyr on github

• Clone the fork you made to your computer

  git clone https://github.com/<your github id>/zephyr
  

• Create a topic branch for your work

  git checkout -b fix_comment_typo
  

• Make changes

• hack

• test

• hack

• etc...

• Add your changes

  git add [file(s) that changed, add -p if you want to be more specific]
  

• Verify you are happy with your changes to be committed

  git diff --cached
  

• Commit changes

  git commit -s
  

The -s automatically adds your Signed-off-by: [name] <email> to your commit message. Your commit will be rejected without this.

Also, please explain what your change does. "Fix stuff" will be rejected. For examples of good commit messages, read the changelog.

• Push your topic branch with your changes to your fork

  git push origin fix_comment_typo
  

• Go to the zephyr project and click the Compare & pull request button for the branch you want to open a pull request with.

• Review the pull request changes, and verify that you are opening a pull request for the appropriate branch. The title and message should reflect the nature/theme of the changes in the PR, say the title is Fix comment typos and the message details any specifics you can provide.

• You might change the zephyr branch, if you are opening a pull request that is intended for a different branch. For example, when you created your topic branch you could have done:

  git checkout -b fix_out_of_date_patch origin/net
  

Then when you get to this pull request screen change the base branch from master to net

• By creating a pull request, the PR is entered into the backlog. A CI job will run to test your changes against a select set of samples. As they start to get worked, they should be placed in the Ready state. PRs that are being worked are In Progress. If a questions come up about the commit that might involve changes to the commit then the PR is placed in Waiting For Response.

• Interactively rebase the offending commit(s) to fix the code review:

  git fetch --all
  git rebase --ignore-whitespace origin master
  git rebase -i <offending-commit-id>^
  

  NOTE: The --ignore-whitespace stops git apply (which is called by rebase) from changing any whitespace when it runs.

  Replace pick with edit or remove the line to delete a commit. Fix the issue in the code review.

  git add [file(s)]
  git rebase --continue
  <update commit comment if needed>
  git push --force origin fix_comment_typo
  

Code Changes

Carefully review the following before submitting a change. These guidelines apply to developers that are new to open source, as well as to experienced open source developers.

Coding Style

Use this coding guideline to ensure that your development complies with the project's style and naming conventions.

In general, follow the Linux kernel coding style, with the following exceptions:

• Add braces to every <code>if</code> and <code>else</code> body, even for single-line code blocks. Use the <code>--ignore BRACES</code> flag to make checkpatch stop complaining.
• Use hard tab stops. Set the tab width 8 spaces. Break lines at 80 characters. If you are trying to align comments after declarations, use spaces instead of tabs to align them.
• Use C89-style single line comments, /* */. The C99-style single line comment, //, is not allowed.
• Use <code>/** */</code> for any comments that need to appear in the documentation.

The Linux kernel GPL-licensed tool checkpatch is used to check coding style conformity. Checkpatch is available in the scripts directory. To invoke it when committing code, edit your <code>.git/hooks/pre-commit</code> file to contain:

#!/bin/sh
set -e exec
exec git diff --cached | ${ZEPHYR_BASE}/scripts/checkpatch.pl - || true

Change Requirements

This section contains guidelines for submitting code changes.

Changes are submitted as Git commits. Each commit must contain:

• a short and descriptive subject line that is 72 characters or fewer, followed by a blank line.
• a change description with your logic or reasoning for the changes, followed by a blank line
• a Signed-off-by line, followed by a colon (Signed-off-by:)

A commit with the above details is considered well-formed.

All changes and topics sent to Github must be well-formed. Informationally, commit messages must include:

• what the change does,
• why you chose that approach,
• what assumptions were made, and
• how you know it works -- for example, which tests you ran.

Commits must build cleanly when applied in top of each other, thus avoiding breaking bisectability. Commits must pass the scripts/checkpatch.pl requirements. Each commit must address a single identifiable issue and must be logically self-contained.

For example: One commit fixes whitespace issues, another renames a function and a third one changes the code's functionality. An example commit file is illustrated below in detail:

doc: Updating tables presentation.

Tables were misaligned; fixed spacing.

Signed-off-by: [email protected]

Each commit must contain the following line at the bottom of the commit message:

Signed-off-by: [email protected]

The name in the Signed-off-by line and your email must match the change authorship information. Make sure your .git/config is set up correctly. Always submit the full set of changes via Github.

When a change is included in the set to enable the other changes, but it will not be part of the final set, let the reviewers know this. Use RFCs (requests for comments) to send work proposals, progress snapshots of your work, or to get early feedback on features or changes that will affect multiple areas in the code base.

If you are submitting a change that has someone else's Signed-off-by, please be sure that you explicitly include that person as a Reviewer in Github.

Gerrit

We previously used gerrit for development, but it is no longer used. We'd like to see patches that are still applicable turned into Pull Requests on GitHub.

You can find the list of pending patches available on gerrit.