Submitting A Patch

From K-3D

Overview

So, you've identified a simple problem or you have a quick new feature in-mind, and you're about to post a message to the mailing list to let us know ... well hold on there, buckaroo! Have you considered just submitting a patch?

• If you have the skills to identify what broke, you have the skills to write a patch.
• A patch is a concise description of your proposed change; in fact, it may take less effort to create a patch than to describe the problem in e-mail - "a patch is worth a thousand words".
• Reduces the workload for other developers. Your patch may be trivial, but it's more efficient when you create it - another developer has to take time to understand your description of the problem, formulate a fix, build, and test it - this time adds-up quickly.
• Your issue may be platform, distribution, or machine-specific. Give developers *some* credit - most have a preferred platform where they do the majority of their work - if they haven't already identified and addressed your problem, it's quite likely that they've never seen it. Asking that person to make platform-specific changes on your behalf is counterproductive, since they have no way of testing those changes and are "flying blind".
• It'll make you feel good.

Creating A Patch In Mercurial

• To see all the new files you created in your top-level source directory do:

$ hg status

• Then for each file you wish to add do:

$ hg add path/to/file

• Or to add all files do:

$ hg add

• To to commit all your newly-added files as a changeset do:

$ hg commit -m "Message describing your changes."

• to export the most recent changeset (the "tip") as a patch to:

$ hg export tip > my.patch

Then send the patch to a developer with commit access to the primary repository.

Creating A Patch In Subversion

We're fairly adamant that creating a patch using Subversion is the only way to work. Note that you don't have to be a developer or have write permissions to create a patch using Subversion:

• Get your source tree from Subversion and build normally.
• Edit files in your subversion source tree as needed. No backups or copies are required. Compile and test.
• If you created new files or new directories, add them to the subversion tree. This is a local operation, you don't have to have subversion write access:

$ svn add my/new/file
$ svn add my/new/directory

• To create your patch, use the svn diff command from the top-level directory of the subversion source tree, and redirect its output to a file:

$ svn diff > my_changes.patch

my_changes.patch will contain your new files and any modifications to existing files.

• Post your patch file to the K-3D Patch Tracker.
• Notify the K-3D mailing list and enjoy your well-deserved praise.

Applying a patch

Now that you're creating and submitting patches like a pro, you may find yourself wanting to apply someone else's patch to your source tree:

• Download the patch and save it to the top-level directory in your source tree.
• Use the GNU patch command to apply the patch:

$ patch -p0 < your_changes.patch

For a thorough introduction to diffs and patching, use the GNU info manual to learn about the diff and patch commands:

$ info Diff

... note that that's "Diff" and not "diff".

Now get on out there and contribute!