GNU Wdiff Developer's Guide
There are many ways to contribute to GNU wdiff. You can file bug reports using the Savannah bug tracker, or by writing an e-mail to the wdiff-bugs mailing list. You can join a language team at the translation project and help writing translations for various GNU applications, wdiff among them. And of course you can contribute modifications to the source code and documentation shipped with wdiff, which I'll describe in more detail below.
If you have a simple fix or improvement to offer for wdiff, it's probably easiest to write a patch against the latest released version. You can submit this patch to the Savannah patch tracker, where it can be discussed and eventually approved for inclusion.
If your patch affects more than a few lines of code, we kindly ask you to assign the copyright for your modification to the Free Software Foundation. To do so, please request the appropriate form.
If you think you have a valuable contribution to make, but don't feel like assigning copyright, please contact us so we can discuss the situation.
Accessing the bzr repository
The steps below should give you a general idea about how to work on the wdiff sources. Of course, if you know bzr, or are willing to read its extensive manuals, you can get much more out of this tool. Generally, bzr distinguishes three concepts: the working tree is the sum of the source files you have on your disk. It might contain ignored files and uncommitted changes. The branch denotes a line of development. You may think of it as a sequence of commits and merges. Below we'll keep the branches alongside each working tree, so you may in most cases ignore this distinction. The repository is the place where bzr stores most of its data. Sharing it between multiple branches saves storage space, so that's what we'll do below. The repository will be a directory containing all branches.
bzr whoami "John Doe <firstname.lastname@example.org>"
Tell bzr who you are. This has to be done only once, when you first use bzr. The command itself will only affect local bzr configuration, but the name and e-mail address you provide will be stored in the commits you make.
bzr init-repo --2a wdiff && cd wdiff
This creates a directory called
wdiffto contain your personal repository. If you have an old version of bazaar not supporting the 2a format, either upgrade bzr or choose any rich-root format available in your bzr setup. The Savannah repository currently uses
--1.6.1-rich-rootto maximize compatibility, but that might change in the future.
bzr clone http://bzr.savannah.gnu.org/r/wdiff/trunk
this creates a directory
trunkwithin the current
wdiffdirectory which will contain the upstream source tree. I would advise not to modify code in that directory, in order to avoid confusion.
bzr clone trunk my-feature
This creates your own local branch, called
my-feature, to contain your modifications. Notice that every bzr branch has a nickname, which will be saved with the commits you make and initially corresponds to the directory name. You can change this using the
bzr nickcommand. Choose a name describing the changes you are up to. By the way, this is the step to start at when you want to work on another, independent feature or fix.
cd my-feature && ./autogen.sh
branch and generates some files usually shipped with a distribution tarball. From here on, the working tree will behave mostly as a snapshot tarball would.
./configure --enable-experimental && make
This builds the application in the usual way.
Now edit the code as you see fit. If you add, remove or rename files, use the corresponding bzr subcommands to track these changes.
make check; make syntax-check
These are some automatic tests to run against your modifications. They are not perfect, so we might consider modifications that fail these checks, but please fix any avoidable errors.
bzr diff; bzr status
This will print a diff of your uncommitted changes, and list the affected files. You should definitely do at least the latter before committing your changes.
This will commit your changes to your local branch. Your default editor, configured using the
EDITORenvironment setting, will be started to prompt you for a commit message. Write a short summary on the first line. If more information is appropriate, include it after a blank line.
bzr send -o my-feature-1.patch ../trunk
This will bundle all the commits included in the current branch but not in trunk into a file called
my-feature-1.patchsuitable for submission to the Savannah patch tracker. It can be easily merged into trunk, maintaining all your development history, commit messages, and authorship attribution.
bzr push lp:~jdoe/wdiff/my-feature
If you are a launchpad user and your user name there is
jdoe, you can use this command to upload and share your branch.
bzr pull -d ../trunk
This updates your copy of the trunk branch from its online version.
bzr merge ../trunk && bzr commit -m "merge from trunk"
This incorporates changes made to trunk into your personal branch. The commit message is given on the command line this time. Notice that concurrent modifications to overlapping portions of code might lead to so-called merge conflicts, which you'll have to resolve manually.
bzr resolve src/wdiff.c && bzr commit -m "merge from trunk"
Assuming you had a merge conflict in
wdiff.c, and you have edited the file to adjust the marked conflicts. Then this command tells bzr that the problem has been resolved, and the merge can now be committed.
wdiff in various bug trackers
wdiff in various distributions
For package maintainers
- Add or update
bzr clean-tree --ignored --detritus
- change version number in
LC_ALL=C make -C doc manual(the
LC_ALL=Cdue a problem with texi2dvi)
gnupload --symlink-regex --to ftp.gnu.org:wdiff wdiff-#.#.#.tar.gz
bzr commit -m "Releasing #.#.#."
bzr tag wdiff-#.#.#
- Ensure ../web is a checkout of the gnu web server repository
find ../web/manual \( -name CVS -prune \) -o \( -type f -print \) | xargs rm
cp -r doc/manual ../web/
- Add (-ko) new files, remove lost files (except .htaccess)
- Set up redirections for removed files in .htaccess
- Add items to the News section of
cvs commit -m "Updated manual to wdiff #.#.#."
- Add Savannah news item
- Make launchpad announcement
- Write mail to email@example.com, firstname.lastname@example.org and email@example.com