Development/Git: Difference between revisions

From MusicBrainz Wiki
Jump to navigationJump to search
No edit summary
(→‎Submitting a patch: Removing reference to sandboxes; they’re no longer a thing.)
 
(24 intermediate revisions by 13 users not shown)
Line 1: Line 1:
Development on the [[MusicBrainz Server]] source code is coordinated using [http://git-scm.com/ Git].
<small>[[Development]] > Git </small>


We use GitHub to host our repositories. Our repos are under [http://github.com/metabrainz /metabrainz], except [https://github.com/BookBrainz BookBrainz].
Development on the [[MusicBrainz Server]] source code is coordinated using [http://git-scm.com/ Git]. The Git web interface, http://git.musicbrainz.org, provides access to viewing the various repositories and even [http://git.musicbrainz.org/gitweb/?p=musicbrainz-server/core.git;a=tree browsing the source code].


== Checking out source code ==
== Checking out source code ==
To create a local copy of the [[MusicBrainz Server]] source code, clone the repository using:
To create a local copy of the [[MusicBrainz Server]] source code, clone the repository using:


git clone git://git.musicbrainz.org/musicbrainz-server/core.git mb_server
<nowiki>git clone https://github.com/metabrainz/musicbrainz-server.git musicbrainz-server
cd musicbrainz-server
</nowiki>


And to stay up to date with the latest changes use:
And to stay up to date with the latest changes use:
Line 12: Line 14:
git pull
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:
The above will clone the latest ''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 tag -l
git checkout <tag name>
git checkout <tag name>


If you need help or are confused send an email to [mailto:support@musicbrainz.org support@musicbrainz.org], or drop by the [http://webchat.freenode.net/?channels=musicbrainz #musicbrainz IRC channel].
If you need help or are confused, send an email to [mailto:support@musicbrainz.org support@musicbrainz.org], or drop by the [http://webchat.freenode.net/?channels=metabrainz #metabrainz IRC channel].


== Development with Git ==
== Development with Git ==


Contributing to MusicBrainz is really simple! First, go to [http://github.com/metabrainz/musicbrainz-server.git the musicbrainz-server repository] and click 'fork' - you'll need a GitHub account to do this. Then clone your repository, and you're good to go!
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/core.git mb_server
<nowiki>git clone https://github.com/<YOUR USER NAME HERE>/musicbrainz-server.git musicbrainz-server</nowiki>
cd musicbrainz-server
cd mb_server
git checkout -b my-cool-feature master
git checkout -b my-cool-feature beta


You probably also want to do <code><nowiki>git remote add upstream https://github.com/metabrainz/musicbrainz-server.git</nowiki></code> 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.


This will give you a local branch to work on your feature. Note that 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 [http://www.kernel.org/pub/software/scm/git/docs/git-format-patch.html git format-patch]. These can then be emailed to the [[Developers Mailing List|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 [http://git.musicbrainz.org git.musicbrainz.org] to push work to. For more information on this, please ask on the [[Developers Mailing List|developers mailing list]] and someone will give you more details.


When you are ready to share your work with us, you should submit a patch; read the [[#Submitting a patch|instructions for submitting a patch]] below.
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:


For more information on this, please drop by the [http://webchat.freenode.net/?channels=metabrainz #metabrainz IRC channel], and someone will give you more details.
git clone ssh://mbgitrw@git.musicbrainz.org:10015/musicbrainz-server/core.git mb_server

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


== Submitting a patch ==
== Submitting a patch ==


If you make changes to the [[MusicBrainz Server]], they'll need to go through our code review process. We use GitHub's pull request system to handle this—if you've already forked the project on GitHub according to the section above, you just need to follow [https://help.github.com/articles/proposing-changes-to-a-project-with-pull-requests/ GitHub's documentation on "Proposing changes to a project with pull requests"]. The target branch will usually be 'master' (though you should have branched off from 'beta').
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:

Be sure to mention other details, such as the JIRA tickets you're fixing (if there isn't a relevant ticket, you may be asked to create one) and what testing you have done—those reviewing your code will want to know. If your code is running anywhere that it can be tested by reviewers, 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!
$ git checkout my-cool-feature
$ git format-patch master
0001-my-feature-is-cool.patch


== The MusicBrainz Workflow ==
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.


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, beta and master. 'production' contains a released version of the code (a tag to be specific), plus possibly a few more commits to fix urgent issues on the production servers. 'master' contains work that has passed testing and code review and will be included in one of the next versions of MusicBrainz. Finally, the 'beta' branch follows 'master', but is frozen one week before the next release (the code in this branch is deployed for live testing at https://beta.musicbrainz.org/). At release time, what was in 'beta' is released and becomes the new 'production'; 'beta' is unfrozen and once more follows the latest code from 'master'.
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:


Let's look at an imaginary example of a small release:
Subject: [PATCH] MBS-123: Added support for My Cool Feature
MusicBrainz has just released a new version, lets call it v-2015-11-30. At this point 'production' has a tag, v-2015-11-30. 'beta' and 'master' are equivalent. Two 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, pull requests are opened for them 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 'master' and will soon continue to 'beta', and more work can happen on 'mbs-2'. A new or revised pull 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 'master'. However, one week has passed since the release and 'beta' is already frozen, so the new code doesn't move on yet. Next time we release, 'beta' is merged into 'production', so the code of 'beta' and 'production' are roughly equivalent again. Finally, a release happens which means 'production' is tagged with a new version, a blog post is posted, and customers can now check this new tag out. Then 'beta' is unfrozen and 'master', which includes 'mbs-2', is merged into it.


== Git Resources ==
== Git Resources ==
Line 59: Line 60:
* [http://www.spheredev.org/wiki/Git_for_the_lazy Git for the lazy]
* [http://www.spheredev.org/wiki/Git_for_the_lazy Git for the lazy]
* [http://www.gnome.org/~newren/eg/ Easy Git (eg)]
* [http://www.gnome.org/~newren/eg/ Easy Git (eg)]
* [https://help.github.com/ github:help] - several help articles on how to do various Git tasks, mostly in relation to GitHub though


[[Category:Development]] [[Category:Server]]
[[Category:Development]] [[Category:Server]] [[Category:To Be Reviewed]] [[Category:How_To]]

Latest revision as of 07:41, 3 August 2019

Development on the MusicBrainz Server source code is coordinated using Git.

We use GitHub to host our repositories. Our repos are under /metabrainz, except BookBrainz.

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 cd musicbrainz-server

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

git pull

The above will clone the latest 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 #metabrainz IRC channel.

Development with Git

Contributing to MusicBrainz is really simple! First, go to the musicbrainz-server repository and click 'fork' - you'll need a GitHub account to do this. Then 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 beta

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 that 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 this, please drop by the #metabrainz IRC channel, and someone will give you more details.

Submitting a patch

If you make changes to the MusicBrainz Server, they'll need to go through our code review process. We use GitHub's pull request system to handle this—if you've already forked the project on GitHub according to the section above, you just need to follow GitHub's documentation on "Proposing changes to a project with pull requests". The target branch will usually be 'master' (though you should have branched off from 'beta').

Be sure to mention other details, such as the JIRA tickets you're fixing (if there isn't a relevant ticket, you may be asked to create one) and what testing you have done—those reviewing your code will want to know. If your code is running anywhere that it can be tested by reviewers, 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, beta and master. 'production' contains a released version of the code (a tag to be specific), plus possibly a few more commits to fix urgent issues on the production servers. 'master' contains work that has passed testing and code review and will be included in one of the next versions of MusicBrainz. Finally, the 'beta' branch follows 'master', but is frozen one week before the next release (the code in this branch is deployed for live testing at https://beta.musicbrainz.org/). At release time, what was in 'beta' is released and becomes the new 'production'; 'beta' is unfrozen and once more follows the latest code from 'master'.

Let's look at an imaginary example of a small release: MusicBrainz has just released a new version, lets call it v-2015-11-30. At this point 'production' has a tag, v-2015-11-30. 'beta' and 'master' are equivalent. Two 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, pull requests are opened for them 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 'master' and will soon continue to 'beta', and more work can happen on 'mbs-2'. A new or revised pull 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 'master'. However, one week has passed since the release and 'beta' is already frozen, so the new code doesn't move on yet. Next time we release, 'beta' is merged into 'production', so the code of 'beta' and 'production' are roughly equivalent again. Finally, a release happens which means 'production' is tagged with a new version, a blog post is posted, and customers can now check this new tag out. Then 'beta' is unfrozen and 'master', which includes 'mbs-2', is merged into it.

Git Resources

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