Submitting patches

From Audacity Wiki
Revision as of 14:45, 25 June 2015 by Galeandrews (talk | contribs) (Move link to audacity/audacity to top of Intro.)
Jump to: navigation, search
If you've made a change to Audacity that you'd like to share with us, a pull request on Github (against Audacity/master) is by far the easiest for us to review and decide on the change. There may be developers willing to look at patch files instead. This page is about such patch files. As we have switched to using Git, this page is mostly of historical interest.
A patch is a file listing the line-by-line differences between one set of files and another, in this case, between your files and ours in Git.

Quick Links:

Which version of Audacity should I patch?

Always patch against Git HEAD if at all possible. If your patch is a tiny bug fix with minimal code lines changed, you could conceivably submit a patch against the latest Audacity release. Patch files are designed to be "redundant", meaning that if the source you are using is out of date, the patch "might" still work.

If your patch adds a new feature, or is an extensive change, please submit your patch against Audacity HEAD. See GitHub for how to obtain HEAD.

How to create a patch

At its simplest:

git diff > patchfile

which should diff with HEAD.

See for detailed help.

Where should I send it?

The best way to interact with us is to subscribe to the Audacity-Devel mailing list. Then send us an email including the patch as a plain text attachment. We all get a lot of email, so:

  • a good subject title prefaced by [PATCH], such as "[PATCH] Fix for bug 1939 Toolbars Crash"
  • a one-line summary of the purpose of the patch
  • a bullet point summary of what it changes

will help enormously.

If you receive an automated response that the patch is being held for moderation because it is too large, be patient, we'll let it through. If the patch is too large to attach to an email, please upload it to a website and give us a link to where it can be downloaded, or tell us the patch is too large and we'll make other arrangements to look at it.

If you are already subscribed to Audacity-Devel and have an account on our Bugzilla, it's fine too to attach a patch to an existing bug report along with your comment about the patch.

If you prefer not to subscribe to a mailing list (for example, if you have a one-off patch for an obvious mistake in our code that you have verified fixes the problem), an alternative is to email our feedback address with your patch.

Why are you ignoring me?

The Audacity developers don't mean to be rude. We will try to respond quickly in full, or failing that, acknowledge your email and let you know when we hope to respond. Some of the reasons we might not accept your patch or respond to your email immediately include:

  • You didn't patch the proper version of Audacity. If you send us a patch for an obsolete version of Audacity, not only will it be difficult for us to port your patch to the latest code, but it may not even be relevant.
  • Your patch is very long - it might take us a while to sort through it and figure out what you did. We welcome contributions, but we like to understand what they do.
  • We're worried that the patch might have unintended consequences - the patch might work great for you, but we've been working with this code for a long time, and we might be anticipating a potential problem that might not be immediately obvious to you.
  • We're busy. We all work on this in our spare time. If for example you contact us around the time of a new release, it may be difficult to respond promptly. If you don't see anything wrong with your patch and you haven't heard anything after a week, please send a reminder email to -devel list using the same subject as the original email. If we're still ignoring you a week later, remind us again! We'll at least try to give you some idea why we haven't responded yet. As soon as we can, we will review your patch and let you know if we can commit it.