michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: contributing: Make instructions cross-platform

Browse source 
The contributing instructions were currently centered exclusively around
Linux. Make them generic and cross-plaform while highlighting the tools
that do not currently work on Windows, namely:

 * sanitycheck
 * checkpatch

Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
This commit is contained in:
Carles Cufi 2018-02-12 15:34:38 +01:00 • committed by Anas Nashif
commit f982a89c4f
1 changed files with 64 additions and 45 deletions
Download patch file Download diff file Expand all files Collapse all files

107
CONTRIBUTING.rst
View file

@ -10,7 +10,6 @@ This document explains how to participate in project conversations, log bugs
and enhancement requests, and submit patches to the project so your patch will and enhancement requests, and submit patches to the project so your patch will
be accepted quickly in the codebase. be accepted quickly in the codebase.
Licensing Licensing
********* *********
@ -85,7 +84,6 @@ When a developer submits a patch, it is a commitment that the contributor has
the right to submit the patch per the license. The DCO agreement is shown the right to submit the patch per the license. The DCO agreement is shown
below and at http://developercertificate.org/. below and at http://developercertificate.org/.
.. code-block:: none .. code-block:: none
Developer's Certificate of Origin 1.1 Developer's Certificate of Origin 1.1
@ -129,7 +127,6 @@ to add the sign-off you can also amend a previous commit with the sign-off by
running ``git commit --amend -s``. If you've pushed your changes to GitHub running ``git commit --amend -s``. If you've pushed your changes to GitHub
already you'll need to force push your branch after this with ``git push -f``. already you'll need to force push your branch after this with ``git push -f``.
Prerequisites Prerequisites
************* *************
@ -143,19 +140,27 @@ and how to set up your development environment as introduced in the Zephyr
.. _Getting Started Guide: .. _Getting Started Guide:
https://www.zephyrproject.org/doc/getting_started/getting_started.html https://www.zephyrproject.org/doc/getting_started/getting_started.html
The examples below use a Linux host environment for Zephyr development.
You should be familiar with common developer tools such as Git and CMake, and You should be familiar with common developer tools such as Git and CMake, and
platforms such as GitHub. platforms such as GitHub.
If you haven't already done so, you'll need to create a (free) GitHub account If you haven't already done so, you'll need to create a (free) GitHub account
on http://github.com and have Git tools available on your development system. on http://github.com and have Git tools available on your development system.
.. note::
The Zephyr development workflow supports all 3 major operating systems
(Linux, macOS, and Windows) but some of the tools used in the sections below
are only available on Linux and macOS. On Windows, instead of running these
tools yourself, you will need to rely on the Continuous Integration (CI)
service ``shippable``, which runs automatically on GitHub when you submit
your Pull Request (PR). You can see any failure results in the Shippable
details link near the end of the PR conversation list.
Repository layout Repository layout
***************** *****************
To clone the main Zephyr Project repository use:: To clone the main Zephyr Project repository use::
$ git clone https://github.com/zephyrproject-rtos/zephyr git clone https://github.com/zephyrproject-rtos/zephyr
The Zephyr project directory structure is described in `Source Tree Structure`_ The Zephyr project directory structure is described in `Source Tree Structure`_
documentation. In addition to the Zephyr kernel itself, you'll also find the documentation. In addition to the Zephyr kernel itself, you'll also find the
@ -208,25 +213,28 @@ Signed-off-by
============= =============
The name in the commit message ``Signed-off-by:`` line and your email must The name in the commit message ``Signed-off-by:`` line and your email must
match the change authorship information. Make sure your *.git/config* is set match the change authorship information. Make sure your :file:`.gitconfig`
up correctly:: is set up correctly:
$ git config --global user.name "David Developer" .. code-block:: console
$ git config --global user.email "david.developer@company.com"
git config --global user.name "David Developer"
git config --global user.email "david.developer@company.com"
gitlint gitlint
========= =======
When you submit a pull request to the project, a series of checks are When you submit a pull request to the project, a series of checks are
performed to verify your commit messages meet the requirements. The same step performed to verify your commit messages meet the requirements. The same step
done during the CI process can be performed locally using the the *gitlint* done during the CI process can be performed locally using the the `gitlint`
command. command.
Install gitlint and run it locally in your tree and branch where your patches Run `gitlint` locally in your tree and branch where your patches have been
have been committed:: committed:
$ sudo pip3 install gitlint .. code-block:: console
$ gitlint
gitlint
Note, gitlint only checks HEAD (the most recent commit), so you should run it Note, gitlint only checks HEAD (the most recent commit), so you should run it
after each commit, or use the ``--commits`` option to specify a commit range after each commit, or use the ``--commits`` option to specify a commit range
@ -235,13 +243,18 @@ covering all the development patches to be submitted.
sanitycheck sanitycheck
=========== ===========
.. note::
sanitycheck does not currently run on Windows.
To verify that your changes did not break any tests or samples, please run the To verify that your changes did not break any tests or samples, please run the
``sanitycheck`` script locally before submitting your pull request to GitHub. To ``sanitycheck`` script locally before submitting your pull request to GitHub. To
run the same tests the CI system runs, follow these steps from within your run the same tests the CI system runs, follow these steps from within your
local Zephyr source working directory:: local Zephyr source working directory:
$ source zephyr-env.sh .. code-block:: console
$ ./scripts/sanitycheck
source zephyr-env.sh
./scripts/sanitycheck
The above will execute the basic sanitycheck script, which will run various The above will execute the basic sanitycheck script, which will run various
kernel tests using the QEMU emulator. It will also do some build tests on kernel tests using the QEMU emulator. It will also do some build tests on
@ -259,8 +272,10 @@ standards <Coding Style>`_ together with a configuration file we've provided:
.. code-block:: bash .. code-block:: bash
uncrustify --replace --no-backup -l C -c # On Linux/macOS
$ZEPHYR_BASE/scripts/uncrustify.cfg my_source_file.c uncrustify --replace --no-backup -l C -c $ZEPHYR_BASE/scripts/uncrustify.cfg my_source_file.c
# On Windows
uncrustify --replace --no-backup -l C -c %ZEPHYR_BASE%\scripts\uncrustify.cfg my_source_file.c
On Linux systems, you can install uncrustify with On Linux systems, you can install uncrustify with
@ -280,7 +295,6 @@ project's style and naming conventions.
.. _Linux kernel coding style: .. _Linux kernel coding style:
https://kernel.org/doc/html/latest/process/coding-style.html https://kernel.org/doc/html/latest/process/coding-style.html
In general, follow the `Linux kernel coding style`_, with the In general, follow the `Linux kernel coding style`_, with the
following exceptions: following exceptions:
@ -292,10 +306,16 @@ following exceptions:
comment, ``//``, is not allowed. comment, ``//``, is not allowed.
* Use ``/** */`` for doxygen comments that need to appear in the documentation. * Use ``/** */`` for doxygen comments that need to appear in the documentation.
The Linux kernel GPL-licensed tool ``checkpatch`` is used to check The Linux kernel GPL-licensed tool ``checkpatch`` is used to check
coding style conformity. Checkpatch is available in the scripts coding style conformity.
directory. To invoke it when committing code, make the file
*$ZEPHYR_BASE/.git/hooks/pre-commit* executable and edit it to contain: .. note::
checkpatch does not currently run on Windows.
Checkpatch is available in the scripts directory. To invoke it when committing
code, make the file *$ZEPHYR_BASE/.git/hooks/pre-commit* executable and edit
it to contain:
.. code-block:: bash .. code-block:: bash
@ -330,26 +350,26 @@ workflow here:
#. On your development computer, clone the fork you just made:: #. On your development computer, clone the fork you just made::
$ git clone https://github.com/<your github id>/zephyr git clone https://github.com/<your github id>/zephyr
This would be a good time to let Git know about the upstream repo too:: This would be a good time to let Git know about the upstream repo too::
$ git remote add upstream https://github.com/zephyrproject-rtos/zephyr.git git remote add upstream https://github.com/zephyrproject-rtos/zephyr.git
and verify the remote repos:: and verify the remote repos::
$ git remote -v git remote -v
#. Create a topic branch (off of master) for your work (if you're addressing #. Create a topic branch (off of master) for your work (if you're addressing
an issue, we suggest including the issue number in the branch name):: an issue, we suggest including the issue number in the branch name)::
$ git checkout master git checkout master
$ git checkout -b fix_comment_typo git checkout -b fix_comment_typo
Some Zephyr subsystems do development work on a separate branch from Some Zephyr subsystems do development work on a separate branch from
master so you may need to indicate this in your checkout:: master so you may need to indicate this in your checkout::
$ git checkout -b fix_out_of_date_patch origin/net git checkout -b fix_out_of_date_patch origin/net
#. Make changes, test locally, change, test, test again, ... (Check out the #. Make changes, test locally, change, test, test again, ... (Check out the
prior chapter on `sanitycheck`_ as well). prior chapter on `sanitycheck`_ as well).
@ -357,19 +377,19 @@ workflow here:
#. When things look good, start the pull request process by adding your changed #. When things look good, start the pull request process by adding your changed
files:: files::
$ git add [file(s) that changed, add -p if you want to be more specific] git add [file(s) that changed, add -p if you want to be more specific]
You can see files that are not yet staged using:: You can see files that are not yet staged using::
$ git status git status
#. Verify changes to be committed look as you expected:: #. Verify changes to be committed look as you expected::
$ git diff --cached git diff --cached
#. Commit your changes to your local repo:: #. Commit your changes to your local repo::
$ git commit -s git commit -s
The ``-s`` option automatically adds your ``Signed-off-by:`` to your commit The ``-s`` option automatically adds your ``Signed-off-by:`` to your commit
message. Your commit will be rejected without this line that indicates your message. Your commit will be rejected without this line that indicates your
@ -379,7 +399,7 @@ workflow here:
#. Push your topic branch with your changes to your fork in your personal #. Push your topic branch with your changes to your fork in your personal
GitHub account:: GitHub account::
$ git push origin fix_comment_typo git push origin fix_comment_typo
#. In your web browser, go to your forked repo and click on the #. In your web browser, go to your forked repo and click on the
``Compare & pull request`` button for the branch you just worked on and ``Compare & pull request`` button for the branch you just worked on and
@ -405,21 +425,21 @@ workflow here:
can create another branch to work on another issue. (Be sure to make your can create another branch to work on another issue. (Be sure to make your
new branch off of master and not the previous branch.):: new branch off of master and not the previous branch.)::
$ git checkout master git checkout master
$ git checkout -b fix_another_issue git checkout -b fix_another_issue
and use the same process described above to work on this new topic branch. and use the same process described above to work on this new topic branch.
#. If reviewers do request changes to your patch, you can interactively rebase #. If reviewers do request changes to your patch, you can interactively rebase
commit(s) to fix review issues. In your development repo:: commit(s) to fix review issues. In your development repo::
$ git fetch --all git fetch --all
$ git rebase --ignore-whitespace upstream/master git rebase --ignore-whitespace upstream/master
The ``--ignore-whitespace`` option stops ``git apply`` (called by rebase) The ``--ignore-whitespace`` option stops ``git apply`` (called by rebase)
from changing any whitespace. Continuing:: from changing any whitespace. Continuing::
$ git rebase -i <offending-commit-id>^ git rebase -i <offending-commit-id>^
In the interactive rebase editor, replace ``pick`` with ``edit`` to select In the interactive rebase editor, replace ``pick`` with ``edit`` to select
a specific commit (if there's more than one in your pull request), or a specific commit (if there's more than one in your pull request), or
@ -429,17 +449,16 @@ workflow here:
As before, inspect and test your changes. When ready, continue the As before, inspect and test your changes. When ready, continue the
patch submission:: patch submission::
$ git add [file(s)] git add [file(s)]
$ git rebase --continue git rebase --continue
Update commit comment if needed, and continue:: Update commit comment if needed, and continue::
$ git push --force origin fix_comment_typo git push --force origin fix_comment_typo
By force pushing your update, your original pull request will be updated By force pushing your update, your original pull request will be updated
with your changes so you won't need to resubmit the pull request. with your changes so you won't need to resubmit the pull request.
Commit Guidelines Commit Guidelines
***************** *****************