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”.
Some tips that will make the merging of your changes into Git much more likely (and you want exactly that, don’t you?):
git diff
and make sure you aren’t
adding, removing, or omitting anything you shouldn’t.
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. |
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. |
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)>
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://my.username@code.wireshark.org: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.
You might get one of the following responses to your patch request:
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.
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.asciidoc. $ $EDITOR docbook/release-notes.asciidoc # If you made any changes, update your commit: $ git commit --amend -a # Upload the change to Gerrit $ git push ssh://my.username@code.wireshark.org: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.