github.com/google/syzkaller@v0.0.0-20240517125934-c0f1611a36d6/docs/contributing.md (about)

     1  # How to contribute to syzkaller
     2  
     3  If you want to contribute to the project, feel free to send a pull request following the [guidelines](contributing.md#guidelines) below.
     4  
     5  In case this is your first pull request to syzkaller, you will need to [sign Google CLA](https://cla.developers.google.com/)
     6  and add yourself to [AUTHORS](/AUTHORS)/[CONTRIBUTORS](/CONTRIBUTORS) files in the first commit.
     7  
     8  ## What to work on
     9  
    10  Extending/improving [system call descriptions](syscall_descriptions.md) is always a good idea.
    11  
    12  Unassigned issues from the [bug tracker](https://github.com/google/syzkaller/issues) are worth doing, but some of them might be complicated.
    13  
    14  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).
    15  
    16  ## Guidelines
    17  
    18  If you want to work on something non-trivial, please briefly describe it on the
    19  [syzkaller@googlegroups.com](https://groups.google.com/forum/#!forum/syzkaller) mailing list first,
    20  so that there is an agreement on the high level approach/design and no duplication of work between contributors.
    21  
    22  Split large changes into smaller, logically cohesive commits. Small commits are much easier and faster to review and iterate on.
    23  
    24  Everything that can be reasonably tested should be tested.
    25  
    26  Provide enough documentation for other users to use the new feature.
    27  
    28  Keep the style of the code, tests, comments, docs, log/error messages consistent with the existing style.
    29  
    30  Continuous Integration (CI) system runs a number of tests and some [opinionated] style checks. They need to pass.
    31  You can test locally with `make presubmit`, if you don't have some prerequisites installed,
    32  you may use `syz-env` (see below).
    33  
    34  ### Commits
    35  
    36  Commit messages should follow the following template:
    37  
    38  ```
    39  dir/path: one-line description
    40  <empty line>
    41  Extended multi-line description that includes
    42  the problem you are solving and how it is solved.
    43  ```
    44  
    45  `dir/path` is a relative path to the main dir this commit changes
    46  (look at examples in the [commit history](https://github.com/google/syzkaller/commits/master)).
    47  If several packages/dirs are significantly affected, then the following format is allowed:
    48  ```
    49  dir1/path1, dir2/path2: one-line description
    50  ```
    51  Though, dirs should not be included if they have only minor changes.
    52  For pervasive changes the following format is allowed:
    53  ```
    54  all: one-line description
    55  ```
    56  
    57  Please pay attention to punctuation. In particular:
    58  
    59  - `one-line description` should *not* start with a Capital letter.
    60  - There is *no dot* at the end of `one-line description`.
    61  - `Extended multi-line description` is full English sentences with Capital letters and dots.
    62  
    63  Commit message line length is limited to 120 characters.
    64  
    65  Also:
    66  
    67  - If your commit fixes an issue, please include `Fixes #NNN` line into commit message
    68  (where `NNN` is the issue number). This will auto-close the issue. If you need to mention
    69  an issue without closing it, add `Update #NNN`.
    70  - For syscall descriptions `*.const` files are checked-in with the `*.txt` changes
    71  in the same commit.
    72  
    73  ### Pull requests
    74  
    75  - Rebase your working branch onto the master branch before sending a pull request to avoid merge conflicts.
    76  - Run `make presubmit` and ensure that it passes before sending a PR.
    77    It may require some additional packages to be installed (try `sudo make install_prerequisites`).
    78  - Provide a brief high-level description in the pull request title.
    79    The pull request text is mostly irrelevant, all the details should be in the commit messages.
    80  - If you're asked to add some fixes to your pull request, please squash the fixes into the old commits.
    81  
    82  ### How to create a pull request on Github
    83  
    84  - First, you need an own git fork of syzkaller repository. Navigate to
    85  [github.com/google/syzkaller](https://github.com/google/syzkaller) and press `Fork` button in the top-right corner of
    86  the page. This will create `https://github.com/YOUR_GITHUB_USERNAME/syzkaller` repository.
    87  
    88  - 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
    89  the repository in the current working directory.
    90  - Remember to `export PATH=$GOPATH/bin:$PATH` if you have not already.
    91  - Then add your repository as an additional origin:
    92  
    93      ```shell
    94      cd syzkaller
    95      git remote add my-origin https://github.com/YOUR_GITHUB_USERNAME/syzkaller.git
    96      git fetch my-origin
    97      git checkout -b my-branch my-origin/master
    98      ```
    99  
   100  This adds git origin `my-origin` with your repository and checks out new branch `my-branch` based on `master` branch.
   101  
   102  - Change/add files as necessary.
   103  - 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.
   104  - Run tests locally (`make install_prerequisites` followed by `make presubmit`).
   105  - Push the commit to your fork on github with `git push my-origin my-branch`.
   106  - Navigate 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).
   107  - 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](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`.
   108  - 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`.
   109  
   110  ### Using syz-env
   111  
   112  Developing syzkaller requires a number of tools installed (Go toolchain, C/C++ cross-compilers, golangci-lint, etc).
   113  Installing all of them may be cumbersome, e.g. due broken/missing packages.
   114  [syz-env](/tools/syz-env) provides a working hermetic development environment based on a Docker container.
   115  If you don't yet have Docker installed, see [documentation](https://docs.docker.com/engine/install),
   116  in particular regarding enabling [sudo-less](https://docs.docker.com/engine/install/linux-postinstall)
   117  Docker (Googlers see go/docker).
   118  
   119  It's recommended to create an alias for `syz-env` script:
   120  ```
   121  alias syz-env="$(go env GOPATH)/src/github.com/google/syzkaller/tools/syz-env"
   122  ```
   123  Then it can be used to wrap almost any make invocation as:
   124  ```
   125  syz-env make format
   126  syz-env make presubmit
   127  syz-env make extract SOURCEDIR=$(readlink -f ~/linux)
   128  ```
   129  Or other commands/scripts, e.g.:
   130  ```
   131  syz-env go test -short ./pkg/csource
   132  ```
   133  Or you may run the shell inside of the container with just `syz-env` and look around.
   134  
   135  To update `syz-env` container to the latest version do:
   136  
   137  ``` bash
   138  docker pull gcr.io/syzkaller/env
   139  ```
   140  
   141  If you do not have access to the `gcr.io` registry, there is also a mirror in `docker.pkg.github.com` registry.
   142  In order to use it, you need to
   143  [authenticate Docker](https://docs.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages)
   144  with your Github account with:
   145  ```
   146  docker login https://docker.pkg.github.com
   147  ```
   148  and then pull the image and retag it to the name expacted by `syz-env`:
   149  ```
   150  docker pull docker.pkg.github.com/google/syzkaller/env
   151  docker tag docker.pkg.github.com/google/syzkaller/env gcr.io/syzkaller/env
   152  ```