Difference between revisions of "Development/Git"

From MusicBrainz Wiki
m
(Submitting a patch)
Line 39: Line 39:
 
== Submitting a patch ==
 
== Submitting a patch ==
  
To submit a patch using "git format-patch", make sure you're on the correct feature branch.  Call git format-patch with the name of the branch you branched off from, like this:
+
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 codereview account.
  
  $ git checkout my-cool-feature
+
Get the latter at http://codereview.musicbrainz.org/.  
  $ git format-patch master
 
  0001-my-feature-is-cool.patch
 
  
It should create one or more patch files.  Attach those to a mail to the [[Developers Mailing List|developers mailing list]] and one of the developers with access to the git repository will apply it for you. If possible, submit a review to http://codereview.musicbrainz.org before sending us mail, so we can more easily give feedback on your patch.
+
For the former, [https://github.com/ github] will serve, if you don't have your own git hosting already. Make an account, then fork https://github.com/metabrainz/musicbrainz-server. After you've made a repository, make your changes and push them back to github. For small changes, you may be able to do them with github's integrated editor.
  
Please add [PATCH] to the subject line, and reference the jira ticket number if you are fixing a known bug. A subject line should look like this:
+
Finally, generate a diff: 'git diff master...HEAD' piped into a file (e.g. 'git diff master...HEAD > blah.diff') should do it, presuming you haven't done anything strange. Upload this file to codereview after hitting 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).  
  
  Subject: [PATCH] MBS-123: Added support for My Cool Feature
+
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 [[MusicBrainz Sandbox|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 ==
 
== The MusicBrainz Workflow ==

Revision as of 19:08, 19 April 2012

Development > Git

Development on the MusicBrainz Server source code is coordinated using Git. The Git web interface, http://git.musicbrainz.org, provides access to viewing the various repositories and even browsing the source code.

Checking out source code

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

git clone git://git.musicbrainz.org/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 IRC channel.

Development with Git

If you want to help contribute to MusicBrainz - it's really simple! All you need to do is branch off master and commit there:

git clone git://git.musicbrainz.org/musicbrainz-server.git musicbrainz-server
cd musicbrainz-server
git checkout -b my-cool-feature master

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 have a few options - if you wish to submit a patches, you should use git format-patch. These can then be emailed to the developers mailing list. If you're doing work on more than one branch, or you'd like to have more control, we are happy to give you a branch or repository on git.musicbrainz.org to push work to. For more information on this, please ask on the developers mailing list and someone will give you more details.

If you have write access to a repository on git.musicbrainz.org, this process changes slightly. Instead of cloning from git://, you should use the following:

git clone ssh://mbgitrw@git.musicbrainz.org:10015/musicbrainz-server.git musicbrainz-server

Notice the ssh username, and the non-standard port, 10015.

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 codereview account.

Get the latter at http://codereview.musicbrainz.org/.

For the former, github will serve, if you don't have your own git hosting already. Make an account, then fork https://github.com/metabrainz/musicbrainz-server. After you've made a repository, make your changes and push them back to github. For small changes, you may be able to do them with github's integrated editor.

Finally, generate a diff: 'git diff master...HEAD' piped into a file (e.g. 'git diff master...HEAD > blah.diff') should do it, presuming you haven't done anything strange. Upload this file to codereview after hitting 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 3 eternal branches: production, master and next. 'master' contains work that has passed testing, code review and will be included in the next version of MusicBrainz. 'production' contains a released version of master (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. You don't really need to concern yourself with this branch. The 'next' branch is our unstable branch, and contains work that developers feel is complete, but still needs more testing from users. Let's look at an imaginary example of a small release:

MusicBrainz has just released a new version, lets call it v-2011-05-20. At this point master has a tag, v-2011-05-20, and production is this tag + a few more commits for our servers. next and master are equivilent. 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 merged into next and out to code review and testing is requested. After testing, MBS-1 is fine and passes review, but MBS-2 isn't good enough. At this point MBS-1 can go into master, and more can commence on MBS-2. Another review goes out, MBS-2 is merged into next again, and out for testing once more. Testers are now happy with this branch, and it passes review, so now MBS-2 also gets merged to master. Now master and next are equivilent again, which means a release can happen. When we decide to release we merge master into production and all branches are roughly equivilent, production = master = next. 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: