Development/Git

From MusicBrainz Wiki
< Development
Revision as of 11:55, 25 January 2013 by Kuno (talk | contribs) (Kuno moved page Git to Development/Git)

Development > Git

Development on the MusicBrainz Server source code is coordinated using Git. We use GitHub for hosting our repositories, see http://github.com/metabrainz for all the repositories.

Checking out source code

To create a local copy of the MusicBrainz Server source code, clone the repository using:

git clone https://github.com/metabrainz/musicbrainz-server.git musicbrainz-server

And to stay up to date with the latest changes use:

git pull

The above will clone the latest stable development version. Alternatively, if you're looking for a stable live release of the MusicBrainz Server, all official releases we make are tagged and accessible using:

git tag -l
git checkout <tag name>

If you need help or are confused send an email to support@musicbrainz.org, or drop by the #musicbrainz-devel IRC channel.

Development with Git

If you want to help contribute to MusicBrainz - it's really simple! First, go to the musicbrainz-server repository and click 'fork' - you'll need a GitHub account to do this. Afterwards, you just need to clone your repository, and you're good to go!

git clone https://github.com/<YOUR USER NAME HERE>/musicbrainz-server.git musicbrainz-server
cd musicbrainz-server
git checkout -b my-cool-feature master

You probably also want to do git remote add upstream https://github.com/metabrainz/musicbrainz-server.git once you're in your new clone, to be able to fetch/pull the most recent code.

This will give you a local branch to work on your feature. Note, this is a slightly different model than you may be used to. This type of development is called "topical branches" - each branch of the code deals with a single isolated feature. This helps us develop by reviewing individual features and bug fixes, without being confused by other possibly unimportant changes.

When you are ready to share your work with us, you should submit a patch; read the instructions for submitting a patch below.

For more information on any this, please ask on the developers mailing list, or drop by the #musicbrainz-devel IRC channel, and someone will give you more details.

Submitting a patch

If you make changes to MusicBrainz Server, they'll need to go through our code review process. You'll need two things: somewhere to put the git branch, and a Review Board account.

To generate a diff, run: 'git diff master...HEAD' piped into a file (e.g. 'git diff master...HEAD > blah.diff'). Upload this file for code review by clicking the "New Review" button. Fill in the other details, such as the branch name and the JIRA tickets you're fixing (if there isn't a relevant ticket, you may be asked to create one); note in the description where your repository is (your GitHub account name, if applicable, will do).

Make sure to note what testing you did -- those reviewing your code will want to know. If your code is running anywhere that it can be tested by reviewers, such as on a sandbox, mention this.

Ultimately, you should get some "Ship It"s or comments to fix; fix anything that needs fixing, and discuss with those who comment on your review. Once it's satisfactory, someone with access will merge your code and it'll get released!

The MusicBrainz Workflow

MusicBrainz uses a simple workflow to get work out for testing, marking it as stable, and deploying the work. There are 2 eternal branches: master and beta. 'master' contains a released version of the code (a tag to be specific), plus a few more little commits we use for the production servers, such as user friendly error pages and further logging. 'beta' contains work that has passed testing, code review and will be included in the next version of MusicBrainz (the code in this branch is deployed for live testing at https://beta.musicbrainz.org/). The 'test' branch is occasionally used for testing patches that need wider community testing but is not yet ready to go into beta. Let's look at an imaginary example of a small release:

MusicBrainz has just released a new version, lets call it v-2012-12-10. At this point master has a tag, v-2012-12-10, and is this tag + possibly a few more commits for our servers. beta and master are equivalent. 2 bugs are reported, so we create separate branches for them: MBS-1 and MBS-2 for example. When they are deemed ready by the owner, they get put out to code review and testing and reviewing is requested. After testing, MBS-1 is fine and passes review, but MBS-2 isn't good enough yet. At this point MBS-1 is merged into beta, and more work can commence on MBS-2. Another review goes out, a new or revised review request for MBS-2 is placed, and testing and reviewing is requested once more. Testers are now happy with this branch, and it passes review, so now MBS-2 also gets merged to beta. Next time we release, beta is merged into master, so the code of beta and master are roughly equivalent again. Finally, a release happens which means master is tagged with a new version, a blog post is posted, and customers can now check this new tag out.

Git Resources

If you're new to Git, don't worry - there is plenty of excellent documentation about how to use it: