Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

<p>We're always looking for contributions! Here are some ways to participate in Cargo's development:</p>
<ul>
	<li>By sending feedback to the user or dev <a href="http://archive.codehaus.org/groups/haus.codehaus.cargo">mailing lists</a>. The feedback could be about something that does not work, something that could be improved, a feature you'd like to see, etc. Or simply it could be that you're a happy user. Letting us know helps a lot!</li>
	<li>By answering emails from others on the <a href="http://archive.codehaus.org/groups/haus.codehaus.cargo">mailing lists</a>.</li>
	<li>By sending code patches. In that case there are a <a class="confluence-link" href="#codingrules" data-anchor="codingrules" data-linked-resource-default-alias="codingrules" data-base-url="http://docs.codehaus.org">few rules</a> you need to know.</li>
	<li>By spreading the word about Cargo!</li>
</ul>

<h3>Creating and submitting a patch</h3>

<p>When you have either completed an issue or just want some feedback on the work you have done, create a patch and attach the patch to the issue in question. We have a couple of guidelines when creating patches:</p>
<ul>
	<li>Always create the patch from the root of the maven project, i.e. where the pom.xml file is.</li>
	<li>Always provide a single patch and not several diff files. If you're adding new files, svn add them first so that they appear within the single patch file.</li>
	<li>If this was a new piece of work without a JIRA issue, create a JIRA issue for it now.</li>
	<li>Attach the patch to the JIRA issue you were working on (do not paste its content in as a comment though). When adding the patch add a comment to the issue explaining what it does. Shortly after, someone will apply the patch and close the issue.</li>
</ul>

<p>An example on how to create a patch from the command line:</p>
<table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
$ svn diff > CARGO-123-something.patch
</pre></td></tr></table>
<p>If you are picking up an issue with a existing patch attached to the issue you can apply the patch to your working directory directly from JIRA like this. The <code>wget</code> and <code>patch</code> commands will only be available if you are on a UNIX platform or using Cygwin on Windows.</p>
<table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
$ wget -O - -q &lt;URL to the patch from JIRA> | patch -p0
</pre></td></tr></table>
<p>If the patch is in a local file <code>CARGO-123.patch</code> and you want to apply that use this command:</p>
<table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
$ patch -p0 &lt; CARGO-123.patch
</pre></td></tr></table>
<p>A couple of notes:</p>
<ul>
	<li>If you are using another tool for creating patches, make sure that the patch doesn't include absolute paths. Including absolute paths in the patch will make the useless for us as we most likely don't have the same directory structure as you.</li>
	<li>Make sure that you follow our <a class="confluence-link" href="/display/CARGO/Cargo+Code+Style" data-linked-resource-id="58599" data-linked-resource-type="page" data-linked-resource-default-alias="Cargo Code Style" data-base-url="http://docs.codehaus.org">code style</a>.</li>
</ul>

<h3>Patch acceptance criteria</h3>

<p>There are a number of criteria that a patch will be judged on:</p>
<ul>
	<li>Whether it works and does what is intended. This one is probably obvious!</li>
</ul>

<ul>
	<li>Whether it fits the spirit of the project. Some patches may be rejected as they take the project in a different direction to that which the current development community has chosen. This is usually discussed on an issue well before a patch is contributed, so if you are unsure, discuss it there or on the mailing lists first. Feel free to continue discussing it (with new justification) if you disagree, or appeal to a wider audience on the mailing lists.</li>
</ul>

<ul>
	<li>Whether it contains tests. It is expected that any patches relating to functionality will be accompanied by unit tests and/or integration tests. It is strongly desired (and will be requested) for bug fixes too, but will not be the basis for not applying it. At a bare minimum, the change should not decrease the amount of automated test coverage. As a community, we are focusing on increasing the current coverage, as there are several areas that do not receive automated testing.</li>
</ul>

<ul>
	<li>Whether it contains documentation. All new functionality needs to be documented for users, even if it is very rough for someone to expand on later. While rough is acceptable, incomplete is not. As with automated testing, as a community we are striving to increase the current coverage of documentation.</li>
</ul>

<p>Above all, don't be discouraged. These are the same requirements the current commiters should hold each other to as well.<br />
And remember, your contributions are always welcome!</p>

<h3>Coding rules</h3>

<p>If you submit a patch you need to follow these rules:</p>
<ul>
	<li>Copyright your code to Vincent Massol (see <a class="confluence-link" href="/display/CARGO/License#License-licenseexplanations" data-anchor="licenseexplanations" data-linked-resource-id="23256" data-linked-resource-type="page" data-linked-resource-default-alias="License#licenseexplanations" data-base-url="http://docs.codehaus.org">license explanations</a>)</li>
	<li>Do not use an @author tag (there was a big discussion on this in Apache land - We need to put the link here)</li>
	<li>Ensure that your code passes the <a class="confluence-link" href="/display/CARGO/Building" data-linked-resource-id="37375" data-linked-resource-type="page" data-linked-resource-default-alias="Building" data-base-url="http://docs.codehaus.org">build</a>. Note that the build contains some <a href="http://svn.codehaus.org/cargo/resources/trunk/build-tools/src/main/resources/build-tools/checkstyle.xml">Checkstyle checks</a> that your code must pass.</li>
	<li>Ensure that you have unit tests and/or integration tests (as part of the existing Cargo test suites)</li>
	<li>Use the same <a class="confluence-link" href="/display/CARGO/Cargo+Code+Style" data-linked-resource-id="58599" data-linked-resource-type="page" data-linked-resource-default-alias="Cargo Code Style" data-base-url="http://docs.codehaus.org">code formatting</a> as the existing code.</li>
	<li>Create a <a href="http://jira.codehaus.org/browse/CARGO?report=com.atlassian.jira.plugin.system.project:openissues-panel">JIRA issue</a> and attach your patch to it.</li>
	<li>Create documentation for what you have added (Ask on the list and you'll get access to Cargo's wiki).</li>
	<li>Add your name on the <a class="confluence-link" href="/display/CARGO/Credits" data-linked-resource-id="10226" data-linked-resource-type="page" data-linked-resource-default-alias="Credits" data-base-url="http://docs.codehaus.org">Credits</a> page.</li>
</ul>

<p>In addition if you plan to contribute big patches that impact existing code, we recommend discussing it on the mailing list first.</p>

<p>Thanks!</p>