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:

It’s the right thing to do. Other people who find your contributions useful
will appreciate them, and you will know that you have helped people in the
same way that the developers of Wireshark have helped you.

You get free enhancements. By making your code public, other developers have
a chance to make improvements, as there’s always room for improvements. In
addition someone may implement advanced features on top of your code, which
can be useful for yourself too.

You save time and effort. The maintainers and developers of Wireshark will
maintain your code as well, updating it when API changes or other changes are
made, and generally keeping it in tune with what is happening with Wireshark.
So if Wireshark is updated (which is done often), you can get a new Wireshark
version from the website and your changes will already be included without any
effort for you.

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.

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.

Please remember

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

3.9.2. Code Requirements

The core maintainers have done a lot of work fixing bugs and making code
compile on the various platforms Wireshark supports.

To ensure Wireshark’s source code quality, and to reduce the workload of the
core maintainers, there are some things you should think about before
submitting a patch.

Pay attention to the coding guidelines

Ignoring the code requirements will make it very likely that your patch will
be rejected.

Follow the Wireshark source code style guide. Just because something
compiles on your platform, that doesn’t mean it’ll compile on all of the other
platforms for which Wireshark is built. Wireshark runs on many platforms, and
can be compiled with a number of different compilers. See Section 7.2, “Coding Style”for
details.

Submit dissectors as built-in whenever possible. Developing a new dissector
as a plugin is a good idea because compiling and testing is quicker, but it’s
best to convert dissectors to the built-in style before submitting for checkin.
This reduces the number of files that must be installed with Wireshark and
ensures your dissector will be available on all platforms.

This is no hard-and-fast rule though. Many dissectors are straightforward so they
can easily be put into "the big pile", while some are ASN.1 based which takes a
different approach, and some multiple sourcefile dissectors are more suitable to
be placed separate as plugin.

Verify that your dissector code does not use prohibited or deprecated APIs.
This can be done as follows:

$ perl <wireshark_root>/tools/checkAPIs.pl <source filename(s)>

Fuzz test your changes! Fuzz testing is a very
effective way to automatically find a lot of dissector related bugs.
You’ll take a capture file containing packets affecting your dissector
and the fuzz test will randomly change bytes in this file, so that unusual
code paths in your dissector are checked. There are tools available to
automatically do this on any number of input files, see:
http://wiki.wireshark.org/FuzzTesting for details.

3.9.3. Uploading your changes

When you’re satisfied with your changes (and obtained any necessary approval
from your organization) you can upload them for review. 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":

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.

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.4. 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: