- 1 Submitting a patch to Mumble
- 2 Producing the patch
- 3 Git crash course
Submitting a patch to Mumble
So you have something you wish to contribute to the Mumble project? Great! There are a few small hoops you'll have to jump through though :)
- Are you the sole, original author of the work you are submitting? If not, is the original author(s) copyright statement and licensing included?
- Can the work be licensed under the BSD license? This is a requirement for being part of Mumble.
- Is the work based on the current development version of Mumble, and not just the last stable release?
We use git, which credits patches both to the author and the commiter. We'll deal with the commiter part, but what we need from you is:
- Your real name (no aliases, please)
- Your prefered email address
- A one-line commit message describing the change.
Submitting the patch
Patches should be submitted on the "Patches" tracker on sourceforge.
Producing the patch
Mumble uses git, so your patch will end up in git sooner or later.
Sending complete files
Please do not do this. If someone else has edited the file between the time you started editing and the time your file should be applied, those changes would be overwritten. So "full file" submissions are only accpeted if they don't overwrite any other changes.
If you're on *nix, a regular 'diff u', to be applied with '-p1' is acceptable.
This is the prefered method of patch, as it contains name, email, commit log and everything else we need directly in the patch.
Git crash course
Here's a short crash course on how to use git with Mumble. First of all, you need git. Install the suitable package for your distribution. If you're on Win32, we recommend msysgit (install it with putting git (and only git) in the path or the "bash only" option -- start the "Git Bash" once you're done)
git config --global user.name "Your Name" git config --global user.email "firstname.lastname@example.org" git config --global branch.autosetuprebase always
(if, and only if, you are on Windows)
git config --global core.autocrlf true
Make a new directory and go into it:
cd mkdir mumble-git cd mumble-git
Clone the upstream Mumble repository:
First, you probably want to make a branch
git branch --track "mybranchname" origin/master git checkout "mybranchname"
You now have a local branch. You can switch back to the original by writing
git checkout master
And back into your branch again with
git checkout "mybranchname"
You'll likely want to keep your local branch around until the changes have been accepted upstream.
Now, on "mybranchname", start editing.
Seeing what you've changed
Will show a list of changed files. To add a completely new file, use
git add "filename"
Will show you the differences you've added. Note that if you're adding completely new file, they won't show up in "git diff" -- there's nothing to diff it from.
Committing your changes
When you are happy with a set of changes:
git commit -a -m "Description of changes. This goes in the Changelog for the next release."
If you just want to modify your last commit a bit, you can use
git commit -a --amend -m "Description of changes."
Note that you should never amend a commit that has made it into the official Mumble repository.
Throwing away your changes
If you make a change you are unhappy with, you can reset the file to the last commit.
git checkout "filename"
Or, if you want everything to go back to the way it was:
git reset --hard
Updating changes from upstream (optional)
git pull --rebase
Will fetch changes that have been done upstream, and try to integrate them with your changes. If you've edited the same files in the same place that has happened upstream, this will fail with a lot of scary looking error messages. If that happens, we recommend you simply do:
git rebase --abort
And then seek help from someone more experienced with git to help you.
Making a patch
When you are ready to send off the patches, make sure you have commited them all, then write:
git format-patch --find-copies-harder --patience origin
This will produce a series of files, one for each commit you've made. Submit the files to the patch tracker on sourceforge :)