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 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...
If you don't have an account on GitHub, create one for free first. Also make sure you set up git on your computer. It's recommended to use SSH to access your own git fork. This workflow is a command line workflow. If you prefer using a UI, GitHub also provides a UI tool for Mac and Windows that can automate some of the following operations.
- Fork on GitHub (click Fork button)
- Clone to computer, use SSH URL (
$ 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-11 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
After having made a Pull Request don't pull/merge anymore, it'll mess up the commit history. If you (have to) rebase, use 'push --force' (
$ git push --force) to send it up to your GitHub repository, this will update the PR too. Be careful not to do this while the core team is working on merging in your PR. Note (to non-UNIX users): the "$ " of the commands mentioned throughout this page is (meant to be) the shell prompt and as such not to be typed in, your actual shell prompt may look different.
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 "":
$ git clone firstname.lastname@example.org:/MuseScore.git $ cd MuseScore
This command 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. Note that the git clone command is using SSH in this case. You need to have SSH set up on your machine. A git:// URL would not work for your local fork, you will not be able to push on it. Alternatively you can use the HTTPS URL. 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 $ git add $ 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 $ git rebase --continue
Another (and shorter) way to update your development branch is
$ git pull --rebase upstream master. Should you have changes that are not yet commited to your branch, use
$ git stash before the rebase and
$ git stash pop after.
Make a pull request to 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. If you are fixing an issue from the tracker, set the issue's status to "patch (code needs review)" with a link to your pull request on GitHub. 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. After having made a Pull Request don't pull/merge anymore, it'll mess up the commit history. If you (have to) rebase, use 'push --force' (
$ git push --force) to send it up to your GitHub repository, this will update the PR too. Be careful not to do this while the core team is working on merging in your PR.
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
Squash your commits
Once you made a pull request, you might be asked to squash your commits together. For example, you might have created several commits to fix a single issue or to develop a single feature and it doesn't make sense to keep all these commits in the MuseScore repository history. You can follow this guide to use
rebase to squash your commits.
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
Test someone else's branch
$ git checkout -b master $ git pull git://github.com//MuseScore.git
Fetch all PRs submitted to upstream
If add this string to your MuseScore/.git/config under section [remote "upstream"]:
fetch = +refs/pull//head:refs/remotes/upstream/pr/
Then whenever you fetch upstream, git will fetch all PRs submitted to musescore. Then you can easily checkout by PR number ####:
$ git checkout upstream/pr/####
Fix multiple issues in a single commit
If a commit fixes multiple issues, then include each issue number in the commit message, e.g.:
"fix #xxxxx, fix #yyyyy, fix #zzzz: message"
so that the issue tracker will update each issue and set their status to fixed.
Run tests on personal Travis
The MuseScore development infrastructure uses Travis Continuous Integration to run tests on every commit and PR submitted the upstream MuseScore repository, but now you can utilize Travis infrastructure for your own person github branches.
- Go to https://travis-ci.org/ and create an account using your github account
- synchronize repositories with your github (should import all your github repos)
- enable the github->travis build hook for MuseScore in https://travis-ci.org/profile/username by turning on the switch next to username/MuseScore
click the gear button (or go to https://travis-ci.org/username/MuseScore/settings) to configure following settings for this repo
enable travis setting for "build pushes"
- optional: add environment variable NOTIFICATION_EMAIL and set to your email address, if you want to get an email when the build completes
Now whenever you push to your github, it will trigger the .travis.yml script, and you can see the the status of the build at https://travis-ci.org/repositories. At this point, will just run tests, but if you would like to also produce a Linux AppImage, follow these next instructions to utilize Bintray:
Upload AppImages to personal Bintray
The above steps to run Travis builds actually also create a portable AppImage so you can test out your commits on (almost) any Linux machine. But are a few more things you need to configure in order for Travis to be able to upload the AppImages to Bintray.
- complete the steps above to run tests on personal Travis
- goto https://bintray.com and create an account using your github account
- in https://bintray.com/username settings for repository, create a new "generic" repository named "MuseScoreDevelopment" (this is where the AppImages will be uploaded to)
- goto https://bintray.com/profile/edit, click on API key
- generate a bintray API key and copy to clipboard
goto https://travis-ci.org/username/MuseScore/settings and add following environment variables:
BINTRAY_API_KEY with value you paste from your clipboard
- BINTRAY_USER set to whatever your bintray user name is (should be same as github username if created travis & bintray accounts from github)
- APPIMAGE_UPLOAD_BRANCHES set to a list of branches (separated by spaces) that you want to upload builds for (or use the magical string "ALL" to upload builds from all branches).
- APPIMAGE_BUILD_ARCHS set to a list of cpu architectures, e.g "x86_64 i686 armhf" (enclosed in quotes), to build AppImages for.
Now try adding a commit to one of the branches you listed in APPIMAGE_UPLOAD_BRANCHES, and wait ~20 minutes. If an AppImage isn't uploaded, look at the bottom of the logs your most recent Travis-ci build jobs for bintray.sh upload sub-jobs. These AppImages will be useful to share with anyone who you want to test our your new feature or bug fix! Please post the link as a comment to your PR, so other devs can easily try it out and provide feeback!