docs/contributing.md: updates

1 files changed, 44 insertions, 34 deletions

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
 <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](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.