Submitting A Patch

From K-3D

Jump to: navigation, search


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!

Personal tools