The development of MuseScore uses GitHub to host the code and manage the collaboration of developers. GitHub is based on git, a popular SCM, initially designed and developed by Linus Torvalds for Linux kernel development.
If you're a developer who wants to work on the MuseScore source code and submit your changes to be merged into the main code, here's how. Thanks to Diaspora for their developer guide, which inspired this one.
- Got 15 minutes and want to learn Git?
- Fork a repo at GitHub: Most of the following on this page (on musescore.org) is from this page on github.com.
- Git documentation - includes videos.
- Git Ready - Learn Git one commit at a time.
- Pro Git book - Free PDF, EPub, online and can be bought in paper form.
- Git Cheat Sheet - From setup to advanced command in a condensed form, color your git diff, status, etc...
- Fork on GitHub (click Fork button)
- Clone to computer (
$ git clone email@example.com:you/MuseScore.git)
- Don't forget to cd into your repo: (
$ cd MuseScore/)
- Set up remote upstream (
$ git remote add upstream git://github.com/musescore/MuseScore.git)
- Create a branch for new issue (
$ git checkout -b 404-new-feature)
- Develop on issue branch. [Time passes, the main MuseScore repository accumulates new commits]
- Commit changes to your local issue branch. (
$ git add . ; git commit -m 'commit message')
- Fetch upstream (
$ git fetch upstream)
- Update local master (
$ git checkout master; git merge upstream/master)
- Rebase issue branch (
$ git checkout 404-new-feature; git rebase master)
- Repeat steps 6-10 until dev is complete
- Push branch to GitHub (
$ git push origin 404-new-feature)
- Start your browser, go to your Github repo, switch to "404-new-feature" branch and press the [Pull Request] button
Fork MuseScore repo to your own account
This will create a copy of MuseScore repository to your own account. To fork, press the fork button in the top right corner on MuseScore GitHub page.
Clone your GitHub fork to your computer
Run a clone command against your GitHub fork. It will look something like this, except that it will use your GitHub account name, instead of "you":
$ git clone firstname.lastname@example.org:you/MuseScore.git $ cd MuseScore
That downloads your copy of MuseScore to a git repository on your development machine. Change directory into the new MuseScore directory. To build MuseScore, you will need to install dependencies, and run the build process. Check the instructions for your platform in the developer handbook.
If you already cloned MuseScore main repository with
git clone git://github.com/musescore/MuseScore.git
You can change the remote url of the origin to your fork with
git remote set-url origin email@example.com:you/MuseScore.git
Choose something to work on
If you don't have a feature in mind, check out the issue tracker, or come ask in IRC (#musescore on freenode.net).
Create a Topical Development Branch
Before you start working on a new feature or bug fix, create a new branch in your local repository that's dedicated to that change. Name it by issue number (if applicable) and description. For example, if you're working on issue #78359, a slur layout problem, create a new branch called 78359-slurlayout, like this:
$ git checkout -b 78359-slurlayout
Write some code!
We are able to offer much help here :). If you can, provide some tests. See the mtest directory.
When you have got something working, commit the changes to your branch on your local Git repo. Firstly add the files you want to commit, and then commit. Don't forget to put a meaningful message. Use git status and git diff to see which files can be added and committed.
$ git status $ git status <filename> $ git add <filenames> $ git commit -m 'fix #78359: Some kind of descriptive message'
If your commit message starts with
fix #xxxxx, with xxxx the issue number in the issue tracker, the issue will be marked as fixed automatically when your commit is pushed in the main repository
Keep your repo up to date with the main repo
In order to get the latest updates from the main repository, do a one-time setup to establish it as a remote by entering:
$ git remote add upstream git://github.com/musescore/MuseScore.git
The main repo will be now known as upstream. Your fork is known as origin. The origin remote is automatically created after cloning your GitHub fork to your computer.
To verify that you have two remotes, you can type:
$ git remote
Rebase your branch on the latest upstream
To keep your development branch up to date, rebase your changes on top of the current state of the upstream master.
# get the changes from upstream $ git fetch upstream # switch to your local master branch $ git checkout master $ git rebase upstream/master # switch to your topical branch $ git checkout 78359-slurlayout #make sure all is committed as necessary in branch before rebasing $ git rebase master
Rebase will put all your commits in the branch on hold, get the last changes, and apply your commits on top of it. You might need to resolve conflicts if you changed a file that has been changed in the main repo. To do so, edit the files, then git add them, and git commit.
Send your changes to MuseScore
When you are ready to send your modified code to MuseScore, push your branch in your origin remote.
$ git push origin 78359-slurlayout
Then do a pull request to MuseScore on GitHub. Go to your GitHub page, select the branch on the left, and press the Pull Request button at the top. Choose your branch, add a comment and submit your pull request. One of the developers with push rights on the main repo will merge your request ASAP. Important: If you haven't signed the MuseScore CLA yet, do this first as it's a requirement for your pull request to be accepted.
Advice & tips
Don't use git commit -a
$ git commit -a
This will perform
git add for all unstaged files and commit. You probably don't want to do that. It's better to use
git status and add files invidually before committing.
Delete a branch
To delete a local branch:
#will first check if the branch has been merged $ git branch -d bugfix #will delete the branch authoritatively $ git branch -D bugfix
To delete a remote branch:
$ git push origin :newfeature
Create and apply a patch
It's better to contribute with a pull request than a patch but if you need to make a patch for any reason here is how.
You have created a local branch with the following command, made some changes and commit locally one or more times.
$ git checkout -b 404-new-feature
To create a patch against the master branch, run
git format-patch master --stdout > 404-new-feature.patch
To apply the resulting patch,
#get stats about the patch without applying it $ git apply --stat 404-new-feature.patch #check if the patch can be applied without problem $ git apply --check 404-new-feature.patch #apply the patch $ git am --signoff < 404-new-feature.patch