Re: [Freeciv-Dev] city-plans

[Greg Wooledge <wooledge@xxxxxxxxxxx>]

F.Schaefer (fransch@xxxxxxxxxxxx) wrote:

> I was asking before a while if there's somebody who could help me to make a
> patch of the changes I did to install city-plans. As far as I know, I didn't
> get any answer. Nobody interested ? In this case I will retire myself from the
> project, of course.

I don't recall seeing your previous message.  Either I somehow overlooked
it, or it never made it to the list server, or the list server failed
to propagate it to me.

Patches are made by a program called "diff".  There is a GNU version,
and there are some commercial-Unix versions of varying quality.  The GNU
version is the best, of course.

I don't really have enough time/motivation to try to write a complete diff
tutorial right now, and I'm probably not sufficiently expert with diff and
CVS to describe the "best" way of doing things anyway.  But here are some
pointers.  (OK, so it came out longer than I thought it would -- it's not
a complete tutorial by any means, but it's a decent quick start guide.)

1) Make sure your patch is made against the latest version of the source
   code you can possibly get (preferably from CVS or a CVS snapshot).

2) Be sure to indicate exactly which version of the source code your patch
   should be applied to (e.g., "version 1.7.2" or "CVS from March 16").

3) There are three different "diff" formats, in descending order of
   goodness: unified diff ("diff -u"), context diff ("diff -c") and
   the original diff ("diff").  The GNU version does unified diffs;
   most commercial versions will only do context diffs (and some won't
   even do those).

4) You need a copy of the original file(s) as well as your modified
   file(s).  If you've forgotten to make a copy of the original source
   code file(s) you've modified, before you modified them, then you'll
   need to re-extract them or re-download them.  I think CVS can automate
   this somehow, but again, I don't have the necessary expertise with CVS.

5) Be sure to specify the original file(s) first, and the modified file(s)
   second.  Otherwise your diffs will be "backwards".
 
6) If you've only modified 1 file, or a small number of files, then you
   can run diff against the file(s) individually, concatenating them
   if necessary:

     diff -u original_file modified_file >> my_patch

   In this case, the "modified_file" should be the normal name of the
   file in question -- for example,

     diff -u unithand.c.orig unithand.c >> my_patch       # RIGHT

   Don't do this:

     diff -u unithand.c unithand.c.modified >> my_patch   # WRONG!

   because that will confuse the program/person applying the patch.

7) If you've modified several files, it's probably best to let diff find
   them all for you.  In this case, you'll want to completely separate
   directory trees -- one with the original code, and one with your
   modified version.  Then you can use the "recursive" option to diff:

     diff -r -u original_directory modified_directory >> my_patch

   When you do this, you'll want to make sure there aren't any object
   files or programs in these directories -- if there are, then diff
   will include references to them in the patch it creates.  In that
   case, either remove those files and rerun the diff, or edit the
   references out of the patch file (see below).

8) If you've created new files, or deleted or renamed files, then there
   are some special options you may have to feed to diff -- check the
   docs.

9) After generating the patch file, *read it*.  Make sure it looks
   sane.  You can use a text editor to correct filenames, or to remove
   "Binary files differ" and "Only in" lines.

10) When submitting patches to freeciv-dev, include them as MIME
    attachments.  If they're larger than about 15-20k, then you should
    compress them with gzip.  If they're smaller than that, then *I* at
    least would prefer them to be uncompressed, because they can be read
    much more easily that way.  (I'm far more likely to take the time to
    look at a patch if it's small, easy to understand, and not compressed.
    If I have to save it in a file and gunzip it, it's more likely I'll
    just wait for someone else to put it in CVS, though I might respond to
    plain-text comments describing the patch if I find them interesting.)

The opinions in this message are solely my own; I have no official status
within the Freeciv project, and I don't even have write access to the
CVS tree (which is definitely a good thing for Freeciv ;-).

-- 
Greg Wooledge                    | Distributed.NET http://www.distributed.net/
wooledge@xxxxxxxxxxx             | because a CPU is a terrible thing to waste.
http://www.kellnet.com/wooledge/ |