GNU Wdiff Developer's Guide

Contributing

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.

Simple contributions

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 sources for GNU wdiff are kept in a Bazaar repository registered with the GNU wdiff project at Savannah. You can use the web interface to browse the latest sources online.

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.

  1. bzr whoami "John Doe <jdoe@example.com>"

    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.

  2. bzr init-repo --2a wdiff && cd wdiff

    This creates a directory called wdiff to 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-root to maximize compatibility, but that might change in the future.

  3. bzr clone http://bzr.savannah.gnu.org/r/wdiff/trunk

    this creates a directory trunk within the current wdiff directory which will contain the upstream source tree. I would advise not to modify code in that directory, in order to avoid confusion.

  4. 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 nick command. 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.

  5. 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.

  6. ./configure --enable-experimental && make

    This builds the application in the usual way.

  7. Now edit the code as you see fit. If you add, remove or rename files, use the corresponding bzr subcommands to track these changes.

  8. 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.

  9. 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.

  10. bzr commit

    This will commit your changes to your local branch. Your default editor, configured using the EDITOR environment 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.

  11. 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.patch suitable for submission to the Savannah patch tracker. It can be easily merged into trunk, maintaining all your development history, commit messages, and authorship attribution.

  12. 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.

  13. bzr pull -d ../trunk

    This updates your copy of the trunk branch from its online version.

  14. 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.

  15. 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.

GNU documentation

wdiff in various bug trackers

wdiff in various distributions

For package maintainers

Release process

  1. make syntax-check
  2. Add or update NEWS section
  3. bzr clean-tree --ignored --detritus
  4. change version number in configure.ac
  5. ./autogen.sh
  6. ./configure --enable-experimental
  7. make distcheck
  8. LC_ALL=C make -C doc manual (the LC_ALL=C due a problem with texi2dvi)
  9. gnupload --symlink-regex --to ftp.gnu.org:wdiff wdiff-#.#.#.tar.gz
  10. bzr commit -m "Releasing #.#.#."
  11. bzr tag wdiff-#.#.#
  12. bzr push
  13. Ensure ../web is a checkout of the gnu web server repository
  14. find ../web/manual \( -name CVS -prune \) -o \( -type f -print \) | xargs rm
  15. cp -r doc/manual ../web/
  16. cd ../web/manual
  17. cvs up
  18. Add (-ko) new files, remove lost files (except .htaccess)
  19. Set up redirections for removed files in .htaccess
  20. cd ..
  21. Add items to the News section of wdiff.html
  22. cvs commit -m "Updated manual to wdiff #.#.#."
  23. Add Savannah news item
  24. Make launchpad announcement
  25. Write mail to info-gnu@gnu.org, wdiff-bugs@gnu.org and coordinator@translationproject.org