3.9. Contribute your changes

If you have finished changing the Wireshark sources to suit your needs, you might want to contribute your changes back to the Wireshark community. You gain the following benefits by contributing your improvements:

There’s no direct way to push changes to the Git repository. Only a few people are authorised to actually make changes to the source code (check-in changed files). If you want to submit your changes, you should upload them to the code review system at https://code.wireshark.org/review. This requires you to set up git as described at Section 3.3.1, “Git over SSH or HTTPS”.

3.9.1. Some Tips For A Good Patch

Some tips that will make the merging of your changes into Git much more likely (and you want exactly that, don’t you?):

  • Use the latest Git sources. It’s a good idea to work with the same sources that are used by the other developers. This usually makes it much easier to apply your patch. For information about the different ways to get the sources, see Section 3.3, “Obtain the Wireshark sources”.
  • Update your sources just before making a patch. For the same reasons as the previous point.
  • Inspect your patch carefully. Run git diff and make sure you aren’t adding, removing, or omitting anything you shouldn’t.
  • Find a good descriptive topic name for your patch. Short, specific names are preferred. snowcone-machine-protocol is good, your name or your company name isn’t.
  • Don’t put unrelated things into one large patch. A few smaller patches are usually easier to apply (but also don’t put every changed line into a separate patch).

In general, making it easier to understand and apply your patch by one of the maintainers will make it much more likely (and faster) that it will actually be applied.

[Note]Please remember

Wireshark is a volunteer effort. You aren’t paying to have your code reviewed and integrated.

3.9.2. Writing a Good Commit Message

When running git commit, you will be prompted to describe the change. Here are some guidelines on how to make that message actually useful to other people (and to scripts that may try to parse it):

  • Provide a very brief description (under 60 characters) of the change in the first line. If the change is specific to a single protocol, start this line with the abbreviated name of the protocol and a colon. If the change is not complete yet prefix the line with [WIP] to inform this change not to be submitted yet. This can later be removed.
  • Insert a single blank line after the first line.
  • Provide a detailed description of the change in the following lines, breaking paragraphs where needed. Limit each line to 80 characters. You can also add metadata at the bottom of the commit message which will be used by Gerrit for searching and triggering Bugzilla integration. Each line of the footer is of the form Label: value. There can be no extra line-breaks between footer lines.

Wireshark currently supports the following metadata tags:

Table 3.1. Commit message tags



A unique hash describing the change, which is generated automatically by the git commit-msg hook which you installed during setup. This should not be changed, even when rebasing or amending a commit following code review. If you pass --no-verify to git commit you will have to add this line yourself.


Make Gerrit automatically add a comment and close the given bug number when the commit is merged. For use when the change does fully fix the issue.


Make Gerrit just add a comment to the referenced bug. For use when the change is related but does not fully fix the issue.


The Bug and Ping-Bug tags are particularly useful if a capture file has been provided via a Bugzilla entry in parallel with the change. All non-trivial fixes to dissectors should try to do this.

Putting all that together, we get the following example:

MIPv6: fix dissection of Service Selection Identifier

APN field is not encoded as a dotted string so the first character is not a length

Bug: 10323
Change-Id: Ia62137c785d505e9d0f1536a333b421a85480741

3.9.3. Code Requirements

To ensure Wireshark’s code quality and to reduce friction in the code review process, there are some things you should consider before submitting a patch:

Follow the Wireshark source code style guide
Wireshark runs on many platforms, and can be compiled with a number of different compilers. It’s easy to write code that compiles on your machine, but doesn’t compile elsewhere. The guidelines at Section 7.2, “Coding Style” describe the techniques and APIs that you can use to write high-quality, portable, and maintainable code in our environment.
Submit dissectors as built-in whenever possible

Developing a new dissector as a plugin can make compiling and testing quicker, but it’s usually best to convert it to built-in before submitting for review. This reduces the number of files that must be installed with Wireshark and ensures your dissector will be available on all platforms.

Dissectors vary, so this is not a hard-and-fast rule. Most dissectors are single C modules that can easily be put into “the big pile.” Some (most notably ASN.1 dissectors) are generated using templates and configuration files. Others are split across multiple source files and are often more suitable to be placed in a separate plugin directory.

Ensure that the Wireshark Git Pre-Commit Hook is in the repository

In your local repository directory, there will be a .git/hooks/ directory, with sample git hooks for running automatic actions before and after git commands. You can also optionally install other hooks that you find useful.

In particular, the pre-commit hook will run every time you commit a change and can be used to automatically check for various errors in your code. The sample git pre-commit hook simply detects whitespace errors such as mixed tabs and spaces. To install it just remove the .sample suffix from the existing pre-commit.sample file.

Wireshark provides a custom pre-commit hook which does additional Wireshark-specific API and formatting checks, but it might return false positives. If you want to install it, copy the pre-commit file from the tools directory (cp ./tools/pre-commit .git/hooks/) and make sure it is executable or it will not be run.

If the pre-commit hook is preventing you from committing what you believe is a valid change, you can run git commit --no-verify to skip running the hooks. Warning: using --no-verify avoids the commit-msg hook, and thus will not automatically add the required Change-ID to your commit. In case you are not updating an existing patch you may generate a Change-ID by running git review -i (or git commit --amend if don’t use git review).

Additionally, if your system supports symbolic links, as all UNIX-like platforms do, you can use them instead of copying files. Running ln -s ./tools/pre-commit .git/hooks creates a symbolic link that will make the hook to be up-to-date with the current master. The same can be done for commit-msg script.

Choose a compatible license

Wireshark is released under the GPL version 2 or later, and it is strongly recommended that incoming code use that license. If that is not possible, it must use a compatible license. The following licenses are currently allowed:

Notable incompatible licenses include Apache 2.0, GPL 3.0, and LGPL 3.0.

Fuzz test your changes
Fuzz testing is a very effective way of finding dissector related bugs. In our case fuzzing involves making random changes to capture files and feeding them to TShark in order to try to make it crash or hang. There are tools available to automatically do this on any number of input files. See https://wiki.wireshark.org/FuzzTesting for details.

3.9.4. Uploading your changes

When you’re satisfied with your changes (and obtained any necessary approval from your organization) you can upload them for review at https://code.wireshark.org/review. This requires a Gerrit Code Review account as described at Section 3.2, “The Wireshark Git repository”.

Changes should be pushed to a magical "refs/for" branch in Gerrit. For example, to upload your new Snowcone Machine Protocol dissector you could push to refs/for/master with the topic "snowcone-machine":

$ git push ssh://[email protected]:29418/wireshark HEAD:refs/for/master/snowcone-machine

The username my.username is the one which was given during registration with the review system.

If you have git-review installed you can upload the change with a lot less typing:

# Note: The "-f" flag deletes your current branch.
$ git review -f

You can push using any Git client. Many clients have support for Gerrit, either built in or via an additional module.

The Change-Id is very relevant in the review process, since it’s the key used to identify one change. See the Gerrit manual for more details.

You might get one of the following responses to your patch request:

  • Your patch is checked into the repository. Congratulations!
  • You are asked to provide additional information, capture files, or other material. If you haven’t fuzzed your code, you may be asked to do so.
  • Your patch is rejected. You should get a response with the reason for rejection. Common reasons include not following the style guide, buggy or insecure code, and code that won’t compile on other platforms. In each case you’ll have to fix each problem and upload another patch.
  • You don’t get any response to your patch. Possible reason: All the core developers are busy (e.g., with their day jobs or family or other commitments) and haven’t had time to look at your patch. Don’t worry, if your patch is in the review system it won’t get lost.

If you’re concerned, feel free to add a comment to the patch or send an email to the developer’s list asking for status. But please be patient: most if not all of us do this in our spare time.

3.9.5. Backporting a change

When a bug is fixed in the master branch it might be desirable or necessary to backport the fix to a stable branch. You can do this in Git by cherry-picking the change from one branch to another. Suppose you want to backport change 1ab2c3d4 from the master branch to master-1.10. Using "pure Git" commands you would do the following:

# Create a new topic branch for the backport.
$ git checkout -b backport-g1ab2c3d4 origin/master-1.10

# Cherry-pick the change. Include a "cherry picked from..." line.
$ git cherry-pick -x 1ab2c3d4

# If there are conflicts, fix them.

# Compile and test the change.
$ make
$ ...

# OPTIONAL: Add entries to docbook/release-notes.adoc.
$ $EDITOR docbook/release-notes.adoc

# If you made any changes, update your commit:
$ git commit --amend -a

# Upload the change to Gerrit
$ git push ssh://[email protected]:29418/wireshark HEAD:refs/for/master-1.10/backport-g1ab2c3d4

If you want to cherry-pick a Gerrit change ID (e.g. I5e6f7890) you can use git review -X I5e6f7890 instead of git cherry-pick and git review instead of git push as described in the previous chapter.