If you want to contribute to the project, feel free to send a pull request following the guidelines below.
In case this is your first pull request to syzkaller, you will need to sign Google CLA and add yourself to AUTHORS/CONTRIBUTORS files in the first commit.
Extending/improving system call descriptions is always a good idea.
Unassigned issues from the bug tracker are worth doing, but some of them might be complicated.
To contribute code or syscall descriptions, at the very least you need to be able to build and run syzkaller, see the instructions here.
If you want to work on something non-trivial, please briefly describe it on the [email protected] mailing list first, so that there is an agreement on the high level approach/design and no duplication of work between contributors.
Split large changes into smaller, logically cohesive commits. Small commits are much easier and faster to review and iterate on.
Everything that can be reasonably tested should be tested.
Provide enough documentation for other users to use the new feature.
Keep the style of the code, tests, comments, docs, log/error messages consistent with the existing style.
Continuous Integration (CI) system runs a number of tests and some [opinionated] style checks. They need to pass.
You can test locally with make presubmit
, if you don't have some prerequisites installed,
you may use syz-env
(see below).
Commit messages should follow the following template:
dir/path: one-line description
<empty line>
Extended multi-line description that includes
the problem you are solving and how it is solved.
dir/path
is a relative path to the main dir this commit changes
(look at examples in the commit history).
If several packages/dirs are significantly affected, then the following format is allowed:
dir1/path1, dir2/path2: one-line description
Though, dirs should not be included if they have only minor changes. For pervasive changes the following format is allowed:
all: one-line description
Please pay attention to punctuation. In particular:
one-line description
should not start with a Capital letter.- There is no dot at the end of
one-line description
. Extended multi-line description
is full English sentences with Capital letters and dots.
Commit message line length is limited to 120 characters.
Also:
- If your commit fixes an issue, please include
Fixes #NNN
line into commit message (whereNNN
is the issue number). This will auto-close the issue. If you need to mention an issue without closing it, addUpdate #NNN
. - For syscall descriptions
*.const
files are checked-in with the*.txt
changes in the same commit.
- Rebase your working branch onto the master branch before sending a pull request to avoid merge conflicts.
- Run
make presubmit
and ensure that it passes before sending a PR. It may require some additional packages to be installed (trysudo make install_prerequisites
). - Provide a brief high-level description in the pull request title. The pull request text is mostly irrelevant, all the details should be in the commit messages.
- If you're asked to add some fixes to your pull request, please squash the fixes into the old commits.
-
First, you need an own git fork of syzkaller repository. Navigate to github.com/google/syzkaller and press
Fork
button in the top-right corner of the page. This will createhttps://github.com/YOUR_GITHUB_USERNAME/syzkaller
repository. -
Checkout main syzkaller repository if you have not already. The simplest way to do it is to run
git clone https://github.com/google/syzkaller
, this will checkout the repository in the current working directory. -
Remember to
export PATH=$GOPATH/bin:$PATH
if you have not already. -
Then add your repository as an additional origin:
cd syzkaller git remote add my-origin https://github.com/YOUR_GITHUB_USERNAME/syzkaller.git git fetch my-origin git checkout -b my-branch my-origin/master
This adds git origin my-origin
with your repository and checks out new branch my-branch
based on master
branch.
- Change/add files as necessary.
- Commit changes locally. For this you need to run
git add
for all changed files, e.g.git add sys/linux/sys.txt
. You can rungit status
to see what files were changed/created. When all files are added (git status
shows no files inChanges not staged for commit
section and no relevant files inUntracked files
section), rungit commit
and enter commit description in your editor. - Run tests locally (
make install_prerequisites
followed bymake presubmit
). - Push the commit to your fork on github with
git push my-origin my-branch
. - Navigate to github.com/google/syzkaller and you should see green
Compare & pull request
button, press it. Then pressCreate pull request
. Now your pull request should show up on pull requests page. - If you don't see
Create pull request
button for any reason, you can create pull request manually. For that navigate to pull requests page, pressNew pull request
, thencompare across forks
and choosegoogle/syzkaller
/master
as base andYOUR_GITHUB_USERNAME/syzkaller
/my-branch
as compare and pressCreate pull request
. - If you decided to rebase commits in
my-branch
(e.g. to rebase them onto updated master) after you created a pull-request, you will need to do a force push:git push -f my-origin my-branch
.
Developing syzkaller requires a number of tools installed (Go toolchain, C/C++ cross-compilers, golangci-lint, etc). Installing all of them may be cumbersome, e.g. due broken/missing packages. syz-env provides a working hermetic development environment based on a Docker container. If you don't yet have Docker installed, see documentation, in particular regarding enabling sudo-less Docker (Googlers see go/docker).
It's recommended to create an alias for syz-env
script:
alias syz-env="$(go env GOPATH)/src/github.com/google/syzkaller/tools/syz-env"
Then it can be used to wrap almost any make invocation as:
syz-env make format
syz-env make presubmit
syz-env make extract SOURCEDIR=$(readlink -f ~/linux)
Or other commands/scripts, e.g.:
syz-env go test -short ./pkg/csource
Or you may run the shell inside of the container with just syz-env
and look around.
To update syz-env
container to the latest version do:
docker pull gcr.io/syzkaller/env
If you do not have access to the gcr.io
registry, there is also a mirror in docker.pkg.github.com
registry.
In order to use it, you need to
authenticate Docker
with your Github account with:
docker login https://docker.pkg.github.com
and then pull the image and retag it to the name expacted by syz-env
:
docker pull docker.pkg.github.com/google/syzkaller/env
docker tag docker.pkg.github.com/google/syzkaller/env gcr.io/syzkaller/env