| Mantis Bug Tracker Developers Guide | ||
|---|---|---|
| <<< Previous | Contributing to MantisBT | Next >>> |
When you have a set of changes to MantisBT that you would like to contribute to the project, there are two preferred methods of making those changes available for project developers to find, retrieve, test, and commit. The simplest method uses Git to generate a specially-formatted patch, and the other uses a public repository to host changes that developers can pull from.
Formatted patches are very similar to file diffs generated by other tools or source control systems, but contain far more information, including your name and email address, and for every commit in the set, the commit's timestamp, message, author, and more. This formatted patch allows anyone to import the enclosed changesets directly into Git, where all of the commit information is preserved.
Using a public repository to host your changes is marginally more complicated than submitting a formatted patch, but is more versatile. It allows you to keep your changesets up to date with the offiicial development repository, and it lets anyone stay up to date with your repository, without needing to constantly upload and download new formatted patches whenever you change anything. There is no need for a special server, as free hosting for public repositories can be found on many sites, such as MantisForge.org, GitHub, or Gitorious.
Assuming that you have an existing local branch that you've kept up to date with master as described in Preparing Feature Branches, generating a formatted patch set should be relatively straightforward, using an appropriate filename as the target of the patch set:
$ git format-patch --binary --stdout origin/master..HEAD > feature_branch.patch
Once you've generated the formatted patch file, you can easily attach it to a bug report, or even use the patch file as an email to send to the developer mailing list. Developers, or other users, can then import this patch set into their local repositories using the following command, again substituting the appropriate filename:
$ git am --signoff feature_branch.patch
We'll assume that you've already set up a public repository, either on a free repository hosting site, or using git-daemon on your own machine, and that you know both the public clone URL and the private push URL for your public repository.
For the purpose of this demonstration, we'll use a public clone URL of git://mantisbt.org/contrib.git, a private push URL of git@mantisbt.org:contrib.git, and a hypothetical topic branch named feature.
You'll need to start by registering your public repository as a 'remote' for your working repository, and then push your topic branch to the public repository. We'll call the remote public for this; remember to replace the URL's and branch name as appropriate:
$ git remote add public git@mantisbt.org:contrib.git $ git push public feature
Next, you'll need to generate a 'pull request', which will list information about your changes and how to access them. This process will attempt to verify that you've pushed the correct data to the public repository, and will generate a summary of changes that you should paste into a bug report or into an email to the developer mailing list:
$ git request-pull origin/master git://mantisbt.org/contrib.git feature
Once your pull request has been posted, developers and other users can add your public repository as a remote, and track your feature branch in their own working repository using the following commands, replacing the remote name and local branch name as appropriate:
$ git remote add feature git://mantisbt.org/contrib.git $ git checkout -b feature feature/feature
If a remote branch is approved for entry into master, then it should first be rebased onto the latest commits, so that Git can remove any unnecessary merge commits, and create a single linear history for the branch. Once that's completed, the branch can be fast-forwarded onto master:
$ git checkout feature $ git rebase master $ git checkout master $ git merge --ff feature
If a feature branch contains commits by non-developers, the branch should be signed off by the developer handling the merge, as a replacement for the above process:
$ git checkout feature $ git rebase master $ git format-patch --binary --stdout master..HEAD > feature_branch.patch $ git am --signoff feature_branch.patch
| <<< Previous | Home | Next >>> |
| Preparing Feature Branches | Up | Database Schema Management |