3.10. Contribute Your Changes
Prev | Chapter 3. Work with the Wireshark sources | Next

## 3.10. 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 main 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://gitlab.com/wireshark/wireshark/-/merge_requests. This requires you to set up git as described at Section 3.4.1, “Git Over SSH Or HTTPS”.

### 3.10.1. Workflow for Contributions

GitLab uses a forking workflow, which looks like this:

Figure 3.1. GitLab Workflow

The major steps of the diagram above are:

- Fork: Create your own repository to work on. You only need to do this once.
- Pull: You should pull from the main repository on a regular basis in order to ensure that your sources are current.
- Push: You should push any time you want to make a merge request or otherwise make your code public.
- Merge Request: submit your change to be included in the Wireshark project.

Let’s look at these steps in more detail.

### 3.10.2. Forking the Source Tree

First, you need to set up your environment. For the steps below we’ll pretend that your username is “henry.perry”.

1. Sign in to https://gitlab.com/wireshark/wireshark by clicking “Sign in / Register” in the upper right corner of the web page and following the login instructions.
2. Add an SSH key to your account as described in the GitLab documentation.
3. Make sure you have a clone of the main repository as described in Section 3.4.1, “Git Over SSH Or HTTPS”.

4. Create your own personal fork of the Wireshark project by pressing the “Fork” button at https://gitlab.com/wireshark/wireshark.

   | Warning
   If you want to make merge requests you must keep your fork public. Making it private will disassociate it from the main Wireshark repository.

5. Add a remote for your personal repository in your source code checkout. The main repository remote is named “upstream”, so we’ll name this one “downstream”.

       $ git remote add downstream git@gitlab.com:henry.perry/wireshark.git

6. Double-check your remotes:

       $ git remote -v
       $ downstream	git@gitlab.com:henry.perry/wireshark.git (fetch)
       $ downstream	git@gitlab.com:henry.perry/wireshark.git (push)
       $ upstream	git@gitlab.com:wireshark/wireshark.git (fetch)
       $ upstream	git@gitlab.com:wireshark/wireshark.git (push)

### 3.10.3. Pulling from Upstream

Before you begin it’s a good idea to synchronize your local repository with the main repository. This is the Pull part of the workflow. Simply re-run the command in Section 3.5.1, “Update Using Git”. You should do this periodically in order to stay up to date and avoid merge conflicts later on.

### 3.10.4. Creating Merge Requests

Now you’re ready to create a merge request (the Push and Merge Request parts of the workflow above).

1. Create a branch for your change:

       $ git checkout -b my-glorious-new-feature upstream/master

   | Note
   Always work from branches; never work directly on `master`. It will be much easier to keep abreast of upstream changes this way.

2. Write some code! See Section 3.10.6, “Some Tips For A Good Patch” and Section 3.10.8, “Code Requirements” for details.

3. Commit your changes. See Section 3.10.7, “Writing a Good Commit Message” for details.

       $ git commit -a

4. Push your changes to your personal repository.

       $ git push downstream HEAD

5. Go to https://gitlab.com/wireshark/wireshark/-/merge_requests. You should see a “Create merge request” button. Press it.

   1. In the merge request page, make sure “Allow commits from members who can merge to the target branch” is selected so that core developers can rebase your change.
   2. You might want to select “Delete source branch when merge request is accepted” as well.
   3. Click the “Submit merge request” button.

### 3.10.5. Updating Merge Requests

At this point various automated tests will be run and someone will review your change. If you need to make changes you can do so by force-pushing it to the same branch in your personal repository.

1. Make changes in your local repository.

       # First, make sure you're on the right branch.
       $ git status
       On branch my-glorious-new-feature

2. Update your code.
3. Rebuild and test your work to be sure it still does what it should.

4. Push your changes to your personal repository.

       # Modify the current commit and force-push...
       $ git commit --amend ...
       $ git push downstream +HEAD
       # ...or keep the current commit as-is add another commit on top of it
       $ git commit ...
       $ git push downstream HEAD

   The `+` sign is shorthand for forcing the push (`-f`).

#### 3.10.5.1. Rebasing Merge Requests

The Wireshark upstream source code is likely to see other changes while you’re doing your work. Git allows you to adapt your in-progress work to these upstream updates, in a process known as rebasing.

Although GitLab provides a Rebase button, you have more control over the process if you do it from the command line:

1. Synchronize your local repository with the command from Section 3.5.1, “Update Using Git”.
2. Switch back to your working branch: `git checkout my-glorious-new-feature`

3. Rebase your working branch: `git rebase master`

   | Tip
   At this stage you may experience a merge conflict, which is when you’ve changed code which has also changed upstream. The rebase will pause to allow you to resolve the conflict. Once you’ve edited the code and reconciled the changes, resume the rebase with the command `git rebase --continue` .

4. Rebuild and test your work to ensure it hasn’t been adversely affected by the upstream changes. (This is especially important if there were any merge conflicts.)
5. Push your changes to your personal repository as described above.

#### 3.10.5.2. Squashing Merge Requests

When the Wireshark developer team is ready to accept your merge request, they may first ask you to squash your changes. This means taking all of the commits you’ve made on your working branch, and combining them into one commit. Here’s how to do it from the command line:

1. Check out your working branch, if you aren’t already on it.

2. Run this command:

       # Perform an "interactive rebase"
       $ git rebase -i master

3. A text editor will appear, listing all of the commits that are in your branch. Each commit will have the word “pick” at the start of the line.
4. Leave the first “pick” alone. In every following line replace “pick” with “squash”.
5. Save your changes and exit your editor.
6. A new editor will appear for you to tailor the commit message of the squashed commit.
7. Once you’re done, push your changes to your personal repository as described above.

### 3.10.6. 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.4, “Obtaining 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` or `git show` as appropriate and make sure you aren’t adding, removing, or omitting anything you shouldn’t.

Give your branch a brief but descriptive name. Short, specific names such as snowcone-machine-protocol are preferred.

Don’t put unrelated things into one large change. Merge requests should be limited in scope. For example, updates to the Snowcone Machine Protocol dissector and the Coloring Rules dialog box should be in separate merge requests.

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.

Thank you in advance for your patience. Wireshark is a volunteer effort. As a result, we can’t guarantee a quick turnaround time.

Preview the final product. Wireshark’s GitLab CI jobs are disabled by default for forks, but if you need to test any CI jobs you can do so under the “Pipelines” section in your repository. For example, if your change might affect Debian (apt) packaging you can run the “build:debian-stable” job.

### 3.10.7. Writing a Good Commit Message

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

Provide a brief description (under 60 characters or so) 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 yet complete prefix the line with “WIP:” to inform this change not to be submitted yet. This be removed when the change is ready to be merged.

Insert a single blank line after the first line. This is required by various formatting tools and helpful to humans.

Provide a detailed description of the change in the lines that follow. Break paragraphs where needed. Limit each line to 80 characters.

You can also reference and close issues in a commit message by prefixing the issue number with a number sign. For example, “closes #5” will close issue number 5.

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. Closes #10323.

### 3.10.8. 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 6.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 if you have setup this hook it will not run.

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.

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:

- BSD 1, 2, 3 clause
- ISC
- LGPL v2 or later, including v2.1
- MIT / X11
- Public domain
- zlib/libpng

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.10.9. Backporting A Change

When a bug is fixed in the master branch it’s sometimes desirable or necessary to backport the fix to a release 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-3.2. You can do so as follows:

    # Create a new topic branch for the backport.
    $ git checkout -b backport-1ab2c3d4 upstream/master-3.2

    # 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.
    $ ninja
    $ ...

    # OPTIONAL: Add entries to doc/Wireshark_Release_Notes.adoc.
    $EDITOR "doc/Wireshark_Release_Notes.adoc"

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

    # Push the change to your working repository.
    git push downstream HEAD

You can also cherry-pick changes in the GitLab web UI.

Prev | Up | Next
3.9. Make Changes To The Wireshark Sources | Home | 3.11. Binary Packaging