contributers.sgml

<chapter id="dev.contrib">
	<title>Contributing to MantisBT</title>

	<para>
		MantisBT uses the source control tool <ulink url="http://git.or.cz">Git</ulink>
		for tracking development of the project.  If you are new to Git, you can
		find some good resources for learning and installing Git in the
		<link linkend="dev.appendix.git">Appendix</link>.
	</para>

	<sect1 id="dev.contrib.setup">
		<title>Initial Setup</title>

		<para>
			There are a few steps the MantisBT team requires of contributers and
			developers when accepting code submissions.  The user needs to configure
			Git to know their full name (not a screen name) and an email address they
			can be contacted at (not a throwaway address).
		</para>

		<para>
			To set up your name and email address with Git, run the following
			commands, substituting your own real name and email address:
		</para>

		<programlisting>
$ git config --global user.name "John Smith"
$ git config --global user.email "jsmith@mantisbt.org"
		</programlisting>

		<para>
			Optionally, you may want to also configure Git to use terminal colors
			when displaying file diffs and other information, and you may want to
			alias certain Git actions to shorter phrases for less typing:
		</para>

		<programlisting>
$ git config --global color.diff "auto"
$ git config --global color.status "auto"
$ git config --global color.branch "auto"

$ git config --global alias.st "status"
$ git config --global alias.di "diff"
$ git config --global alias.co "checkout"
$ git config --global alias.ci "commit"
		</programlisting>

	</sect1>

	<sect1 id="dev.contrib.clone">
		<title>Cloning the Repository</title>

		<para>
			The primary repository for MantisBT is hosted and available in multiple
			methods depending on user status and intentions.  For most contributers,
			the public clone URL is
			<ulink url="git://mantisbt.org/mantisbt.git">git://mantisbt.org/mantisbt.git</ulink>.
			To clone the repository, perform the following from your target workspace:
		</para>

		<programlisting>
$ git clone git://mantisbt.org/mantisbt.git
		</programlisting>

		<para>
			If you are a member of the MantisBT development team with write access to
			the repository, there is a special clone URL that uses your SSH key to
			handle access permissions and allow you read and write access.  Note: This
			action <emphasis>will fail</emphasis> if you do not have developer access
			or do not have your public SSH key set up correctly.
		</para>

		<programlisting>
$ git clone git@mantisbt.org:mantisbt.git
		</programlisting>

		<para>
			After performing the cloning operation, you should end up with a new
			directory in your workspace, <filename>mantisbt/</filename>.  By default,
			it will only track code from the primary remote branch, <literal>master</literal>,
			which is the latest development version of MantisBT.  For contributers
			planning to work with stable release branches, or other development
			branches, you will need to set up local tracking branches in your
			repository.  The following commands will set up a tracking branch for the
			current stable branch, <literal>master-1.1.x</literal>.
		</para>

		<programlisting>
$ git checkout -b master-1.1.x origin/master-1.1.x
		</programlisting>

	</sect1>

	<sect1 id="dev.contrib.branch">
		<title>Maintaining Tracking Branches</title>

		<para>
			In order to keep your local repository up to date with the official,
			there are a few simple commands needed for any tracking branches that you
			may have, including <literal>master</literal> and
			<literal>master-1.1.x</literal>.
		</para>

		<para>
			First, you'll need to got the latest information from the remote repo:
		</para>

		<programlisting>
$ git fetch origin
		</programlisting>

		<para>
			Then for each tracking branch you have, enter the following commands:
		</para>

		<programlisting>
$ git checkout master
$ git rebase origin/master
		</programlisting>

		<para>
			Alternatively, you map combine the above steps into a single command
			for each remote tracking branch:
		</para>

		<programlisting>
$ git checkout master
$ git pull --rebase
		</programlisting>
	</sect1>

	<sect1 id="dev.contrib.prepare">
		<title>Preparing Feature Branches</title>

		<para>
		</para>
	</sect1>

	<sect1 id="dev.contrib.submit">
		<title>Submitting Changes</title>

		<para>
			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.
		</para>

		<para>
			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.
		</para>

		<para>
			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
			<ulink url="http://git.mantisforge.org">MantisForge.org</ulink>,
			<ulink url="http://github.com">GitHub</ulink>, or
			<ulink url="http://gitorious.com">Gitorious</ulink>.
		</para>

		<sect2 id="dev.contrib.submit.patch">
			<title>Via Formatted Patches</title>

			<para>
				Assuming that you have an existing local branch that you've kept up to date
				with <literal>master</literal> as described in
				<link linkend="dev.contrib.prepare">Preparing Feature Branches</link>,
				generating a formatted patch set should be relatively straightforward,
				using an appropriate filename as the target of the patch set:
			</para>

			<programlisting>
$ git format-patch --binary --stdout origin/master..HEAD > feature_branch.patch
			</programlisting>

			<para>
				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:
			</para>

			<programlisting>
$ git am --signoff feature_branch.patch
			</programlisting>

		</sect2>

		<sect2 id="dev.contrib.submit.repo">
			<title>Via Public Repository</title>

			<para>
				We'll assume that you've already set up a public repository, either on a
				free repository hosting site, or using <command>git-daemon</command> on your own
				machine, and that you know both the public clone URL and the private push
				URL for your public repository.
			</para>

			<para>
				For the purpose of this demonstration, we'll use a public clone URL of
				<literal>git://mantisbt.org/contrib.git</literal>, a private push URL of
				<literal>git@mantisbt.org:contrib.git</literal>, and a hypothetical
				topic branch named <literal>feature</literal>.
			</para>

			<para>
				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 <literal>public</literal> for this; remember to
				replace the URL's and branch name as appropriate:
			</para>

			<programlisting>
$ git remote add public git@mantisbt.org:contrib.git
$ git push public feature
			</programlisting>

			<para>
				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:
			</para>

			<programlisting>
$ git request-pull origin/master git://mantisbt.org/contrib.git feature
			</programlisting>

			<para>
				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:
			</para>

			<programlisting>
$ git remote add feature git://mantisbt.org/contrib.git
$ git checkout -b feature feature/feature
			</programlisting>

		</sect2>

	</sect1>

</chapter>