From f8f57555cd9496188673f14b02ce8e1f13ce508c Mon Sep 17 00:00:00 2001 From: Andrey Konovalov Date: Fri, 8 May 2020 18:53:27 +0200 Subject: docs/contributing.md: updates --- docs/contributing.md | 78 +++++++++++++++++++++++++++++----------------------- 1 file changed, 44 insertions(+), 34 deletions(-) (limited to 'docs/contributing.md') diff --git a/docs/contributing.md b/docs/contributing.md index 8675fa1d3..6d5a1f321 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,53 +1,63 @@ # How to contribute to syzkaller -If you want to contribute to the project, feel free to send a pull request following the guidelines below. +If you want to contribute to the project, feel free to send a pull request following the [guidelines](contributing.md#guidelines) below. + +## What to work on + +Extending/improving [system call descriptions](syscall_descriptions.md) is always a good idea. + +Unassigned issues from the [bug tracker](https://github.com/google/syzkaller/issues) 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](/docs/setup.md). + +If you want to work on something non-trivial, please briefly describe it on the [syzkaller@googlegroups.com](https://groups.google.com/forum/#!forum/syzkaller) mailing list first, +so that there is agreement on high level approach and no duplication of work between contributors. ## Guidelines -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) and add yourself to -[AUTHORS](/AUTHORS)/[CONTRIBUTORS](/CONTRIBUTORS) files (in case this is your -first pull request to syzkaller). +In case this is your first pull request to syzkaller, you need to: + +- Sign [Google CLA](https://cla.developers.google.com/) (if you don't a bot will ask you to do that). +- Add yourself to [AUTHORS](/AUTHORS)/[CONTRIBUTORS](/CONTRIBUTORS) files in the first commit. + +### Commits -Some guildelines to follow: +Commit messages should follow the following template: -- Commit messages should follow the following template: ``` dir/path: one-line description 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](https://github.com/google/syzkaller/commits/master)).\ +(look at examples in the [commit history](https://github.com/google/syzkaller/commits/master)). + Please pay attention to punctuation. In particular: -- `one-line description` does *not* start with a Capital letter. -- there is *no dot* at the end of `one-line description`. -- `Extended multi-line description` is full English sentenses with Capital letters and dots. + +- `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. Also: + - If you commit fixes an issue, please include `Fixes #NNN` line into commit message -(where `NNN` is issue number). This will auto-close the issue. If you need to mention +(where `NNN` is the issue number). This will auto-close the issue. If you need to mention an issue without closing it, add `Update #NNN`. -- The pull request text is mostly irrelevant. -- 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`). -- `*.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. -- If you're asked to add some fixes to your pull requested, please squash the new commits with the old ones. - -## What to work on - -Extending/improving [system call descriptions](syscall_descriptions.md) is always a good idea. +- For syscall descriptions `*.const` files are checked-in with the `*.txt` changes +in the same commit. -Unassigned issues from the [bug tracker](https://github.com/google/syzkaller/issues) are worth doing, but some of them might be complicated. - -If you want to contribute code or syscall descriptions, at the very least you need to be able to build and run syzkaller, see the instructions [here](/docs/setup.md). +### Pull requests -If you want to work on something non-trivial, please briefly describe it on the [syzkaller@googlegroups.com](https://groups.google.com/forum/#!forum/syzkaller) mailing list first, -so that there is agreement on high level approach and no duplication of work between contributors. +- 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 (try `sudo 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. -## How to create a pull request +### How to create a pull request on Github - 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 @@ -59,12 +69,12 @@ the repository in `$GOPATH/src/github.com/google/syzkaller`. - Remember to `export PATH=$GOPATH/bin:$PATH` if you have not already. - Then add your repository as an additional origin: -```shell -cd $GOPATH/src/github.com/google/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 -``` + ```shell + cd $GOPATH/src/github.com/google/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. -- cgit mrf-deployment