1 # How to contribute to syzkaller 2 3 ## Guidelines 4 5 If you want to contribute to the project, feel free to send a pull request. 6 7 Before sending a pull request you need to [sign Google CLA](https://cla.developers.google.com/) (if you don't a bot will ask you to do that) 8 and add yourself to [AUTHORS](/AUTHORS)/[CONTRIBUTORS](/CONTRIBUTORS) files (in case this is your first pull request to syzkaller). 9 10 Some guildelines to follow: 11 12 - Commit messages should follow the following template: 13 ``` 14 package: one-line description 15 <empty line> 16 Extended multi-line description that includes 17 the problem you are solving and how it is solved. 18 ``` 19 `package` is the package/tool this commit changes 20 (look at examples in the [commit history](https://github.com/google/syzkaller/commits/master)) 21 - The pull request text is mostly irrelevant 22 - Run `make presubmit` and ensure that it passes before sending a PR. It may require some additional packages to be installed (try `sudo make install_prerequisites`) 23 - Rebase your pull request onto the master branch before submitting 24 - If you're asked to add some fixes to your pull requested, please squash the new commits with the old ones 25 26 ## What to work on 27 28 Extending/improving [system call descriptions](syscall_descriptions.md) is always a good idea. 29 30 Unassigned issues from the [bug tracker](https://github.com/google/syzkaller/issues) are worth doing, but some of them might be complicated. 31 32 If you want to work on something non-trivial, please briefly describe it on the [syzkaller (a] googlegroups.com](https://groups.google.com/forum/#!forum/syzkaller) mailing list first, 33 so that there is agreement on high level approach and no duplication of work between contributors. 34 35 ## How to create a pull request 36 37 - First, you need an own git fork of syzkaller repository. Nagivate to [github.com/google/syzkaller](https://github.com/google/syzkaller) and press `Fork` button in the top-right corner of the page. This will create `https://github.com/YOUR_GITHUB_USERNAME/syzkaller` repository. 38 - Checkout main syzkaller repository if you have not already. To work with `go` command the checkout must be under `$GOPATH`. The simplest way to do it is to run `go get github.com/google/syzkaller`, this will checkout the repository in `$GOPATH/src/github.com/google/syzkaller`. 39 - Then add your repository as an additional origin: 40 41 ```shell 42 cd $GOPATH/src/github.com/google/syzkaller 43 git remote add my-origin https://github.com/YOUR_GITHUB_USERNAME/syzkaller.git 44 git fetch my-origin 45 git checkout -b my-branch master 46 ``` 47 48 This adds git origin `my-origin` with your repository and checks out new branch `my-branch` based on `master` branch. 49 50 - Change/add files as necessary. 51 - 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 run `git status` to see what files were changed/created. When all files are added (`git status` shows no files in `Changes not staged for commit` section and no relevant files in `Untracked files` section), run `git commit` and enter commit description in your editor. 52 - Run tests locally (`make install_prerequisites` followed by `make presubmit`). 53 - *Important* If you've run `go fmt` and you're seeing the presubmit fail on 54 `check_diff`, then you may need to use an older version of go to format your 55 code. (Version 1.11 in particular introduced a breaking change, see 56 [here](https://github.com/golang/go/issues/25161) and 57 [here](https://github.com/golang/go/issues/26228) for details). A 58 simple way to do this is: 59 ```go get golang.org/dl/go1.10 60 go1.10 download 61 # Default download path is here. 62 ~/sdk/go1.10/bin/go fmt [target files]``` 63 - Push the commit to your fork on github with `git push my-origin my-branch`. 64 - Nagivate to [github.com/google/syzkaller](https://github.com/google/syzkaller) and you should see green `Compare & pull request` button, press it. Then press `Create pull request`. Now your pull request should show up on [pull requests page](https://github.com/google/syzkaller/pulls). 65 - If you don't see `Create pull request` button for any reason, you can create pull request manually. For that nagivate to [pull requests page](https://github.com/google/syzkaller/pulls), press `New pull request`, then `compare across forks` and choose `google/syzkaller`/`master` as base and `YOUR_GITHUB_USERNAME/syzkaller`/`my-branch` as compare and press `Create pull request`. 66 - 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`. 67
