If you have finished changing the Ethereal sources to suit your needs, you might want to contribute your changes back to the Ethereal SVN repository.
You gain the following benefits by contributing your improvements back to the community:
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 Ethereal have helped people
The developers of Ethereal might improve your changes even more, as there's always room for improvements. Or they may implement some advanced things on top of your code, which can be useful for yourself too.
The maintainers and developers of Ethereal will maintain your code as well, fixing it when API changes or other changes are made, and generally keeping it in tune with what is happening with Ethereal. So if Ethereal is updated (which is done often), you can get a new Ethereal version from the website and your changes will already be included without any effort for you. The maintainers and developers of Ethereal will maintain your code as well, fixing it when API changes or other changes are made, and generally keeping it in tune with what is happening with Ethereal.
There's no direct way to commit changes to the SVN 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 make a diff file (a patch) and send it to the developer mailing list.
A diff file is a plain text file containing the differences between a pair of files (or multiple of such pairs).
![]() | Tip! |
---|---|
A diff file is often also called a patch, as it can be used to patch an existing source file or tree with changes from somewhere else. |
The Ethereal community is using patches to transfer source code changes between the authors.
A patch is both readable by humans and (as it is specially formatted) by some dedicated tools.
Here is a small example of a patch file (XXX - generate a better example):
diff -ur ../ethereal-0.10.6/epan/dissectors/packet-dcerpc.c ./epan/dissectors/packet-dcerpc.c --- ../ethereal-0.10.6/epan/dissectors/packet-dcerpc.c 2004-08-12 15:42:26.000000000 -0700 +++ ./epan/dissectors/packet-dcerpc.c 2004-08-19 18:48:32.000000000 -0700 @@ -282,6 +282,7 @@ /* we need to keep track of what transport were used, ie what handle we came * in through so we know what kind of pinfo->private_data was passed to us. */ +/* Value of -1 is reserved for "not DCE packet" in packet_info.dcetransporttype. */ #define DCE_TRANSPORT_UNKNOWN 0 #define DCE_CN_TRANSPORT_SMBPIPE 1
The plus sign at the start of a line indicates an added line, a minus sign indicates a deleted line compared to the original sources.
As we always use so called "unified" diff files in Ethereal development, three unchanged lines before and after the actual changed parts are included. This will make it much easier for a merge/patch tool to find the right place(s) to change in the existing sources.
There are several ways to generate such a patch.
svn diff -u [changed_files] > svn.diff
XXX - add more details
Most (if not all) of the GUI Subversion clients (RapidSVN, TortoiseSVN, ...) have a built-in "diff" feature.
If you use TortoiseSVN:
TortoiseSVN (to be precise subversion) keeps track of the files you have changed in the directories it controls, and will generate for you a unified diff file compiling the differences. To do so - after updating your sources from the SVN repository if needed - just right-click on the highest level directory and choose "TortoiseSVN" -> "Create patch...". You will be asked for a name and then the diff file will be created. The names of the files in the patch will be relative to the directory you have right-clicked on, so it will need to be applied on that level too.
When you create the diff file, it will include any difference TortoiseSVN finds in files in and under the directory you have right-clicked on, and nothing else. This means that changes you might have made for your specific configuration - like modifying "config.nmake" so that it uses your lib directory - will also be included, and you will need to remove these lines from the diff file. It also means that only changes will be recorded, i.e. if you have created new files -say, a new packet-xxx for a new protocol dissector- it will not be included in the diff, you need to add it separately. And, of course, if you have been working separately in two different patches, the .diff file will include both topics, which is probably not a good idea.
A diff file is generated, by comparing two files or directories between your own working copy and the "official" source tree. So to be able to do a diff, you should have two source trees on your computer, one with your working copy (containing your changes), and one with the "official" source tree (hopefully the latest SVN files) from www.ethereal.com.
If you have only changed a single file, you could type something like this:
diff -r -u --strip-trailing-cr svn-file.c work-file.c > foo.diff
To get a diff file for your complete directory (including subdirectories), you could type something like this:
diff -r -u --strip-trailing-cr ./svn-dir ./working-dir > foo.diff
It's a good idea to do a make distclean
before the
actual diff call, as this will remove a lot
of temporary files which might be otherwise included in the diff. After
doing the diff, you should edit the foo.diff
file and remove unnecessary things, like your private changes to the
config.nmake
file.
Table 4.1. Some useful diff options
Option | Purpose |
---|---|
-r | Recursively compare any subdirectories found. |
-u | Output unified context. |
--strip-trailing-cr | Strip trailing carriage return on input. This is useful for Win32 |
-x PAT | Exclude files that match PAT. This could be something like -x *.obj to exclude all win32 object files. |
The diff tool has a lot options, you will get a list with:
diff --help
Some tips that will make the merging of your changes into the SVN tree much more likely (and you want exactly that, don't you :-):
Use the latest SVN sources, or alike. It's a good idea to work with the same sources that are used by the other developer's, this makes it usually much easier to apply your patch. For information about the different ways to get the sources, see Section 4.4, “Obtain the Ethereal sources”.
Update your SVN sources just before making a patch. For the same reasons as the previous point.
Do a "make clean" before generating the patch. This removes a lot of unneeded intermediate files (like object files) which can confuse the diff tool generating a lot of unneeded stuff which you have to remove by hand from the patch again.
Find a good descriptive filename for your patch.
Think a moment to find a proper name for your patch file. Often a
filename like ethereal.diff
is used, which isn't
really helpful if keeping several of these files and find the right
one later. For example: If you want to commit changes to the datatypes
of dissector foo, a good filename might be:
packet-foo-datatypes.diff
.
Follow the Ethereal source code style guide. Ethereal runs on many platforms, and can be compiled with a number of different compilers. See Section 6.2, “Coding styleguides” for details.
![]() | Note! |
---|---|
Just because something compiles on your platform, that doesn't mean it'll compile on all of the other platforms for which Ethereal is built. |
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 seperate patch :-).
Remove any parts of the patch not related to the
changes you want to submit. You can use a text editor for this.
A common example for win32 developers are the differences in your private
config.nmake
file.
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: you don't pay the person "on the other side of the mail" for his/her effort applying your patch!
After generating a patch of your changes, you might want to have your changes included into the SVN server.
You should send an email to mailto:ethereal-dev[AT]ethereal.com containing:
subject: [PATCH] and a short description of your changes
body: the reasons for your changes and a short description what you changed and how you changed it
attachment: the patch file
Don't include your patch into the mail text, as this often changes the text formatting and makes it much harder to apply your patch.
When someone from the Ethereal core maintainers finds the time to look at your patch, it will be merged into the SVN repository, so the latest SVN revisions and new releases will include it :-)
You might get one of the following responses from your mail:
your patch is checked into the SVN repository :-)
your patch is rejected (and you get a response mail like: please change xy because of ...). Possible reasons: you didn't followed the style guides, your code was buggy or insecure, your code does not compile on all of the supported platforms, ... So please fix the mentioned things and send a newly generated patch.
you don't get any reponse to your patch (even after a few days or so). Possible reason: your patch might simply get lost, as all core maintainers were busy at that time and forgot to look at your patch. Simply send a mail asking if the patch was forgotten or if someone is still looking at it.