View source for Development/Contribute code

{{#pagetitle:Contribute code}}
[[Main Page]] > [[Development]] > Development/Contribute code

Thank you for your interest in contributing code to the Access to Memory (AtoM) project! Third-party patches and community development help keep the AtoM project vibrant and responsive to our users' needs. We hope to simplify the contribution process as much as possible, and have included some simple guidelines here to help you get started.

If you find a bug in this project or would like to make an enhancement, please contribute a patch and help us improve AtoM!

We recommend checking out the following pages prior to preparing a code contribution:

* Find out more about our Code Review process here: [[Development/Code review|Code review]]
* Learn about our Coding standards here: [[Development/Coding standard|Coding standard]]
* Find information about our Code repository here: [[Resources/Code repository|Code repository]]


<admonition type="seealso">
* Interested in contributing to our project documentation? We have a separate page for that! See:  [[Resources/Documentation/Contribute|Contribute documentation]]
* Check out our wiki page about our code repository - includes helpful links and tips to get you started: [[Resources/Code repository]]
</admonition>


= Copyright and license =
In order to accept any patches or code commits, contributors must first sign this '''[https://www.qubit-toolkit.org/accesstomemory-contributor-agreement-2014.pdf contributor agreement (PDF)]'''.

===Why do I have to sign a Contributor's Agreement?===

One of the key challenges for open source software is to support a collaborative development environment while protecting the rights of contributors and users over the long-term.

Unifying AtoM copyrights through contributor agreements is the best way to protect the availability and sustainability of AtoM over the long-term as free and open-source software. In all cases, contributors who sign the Contributor's Agreement retain full rights to use their original contributions for any other purpose outside of AtoM, while enabling Artefactual Systems, any successor Foundation which may eventually take over responsibility for AtoM, and the community AtoM users to benefit from their collaboration and contributions in this open source project.

[http://artefactual.com Artefactual Systems] has made the decision and has a proven track record of making our intellectual property available to the community at large. By standardizing contributions on these agreements the AtoM intellectual property position does not become too complicated. This ensures our resources are devoted to making our project the best they can be, rather than fighting legal battles over contributions.

===Do you have examples of Contributor's Agreements from other projects?===

The AtoM contributor's agreement is based almost verbatim on the [http://apache.org Apache Foundation]'s individual [http://www.apache.org/licenses/icla.txt contributor license].

Examples from other projects include: [https://www.irods.org/index.php/iRODS_Contributor%E2%80%99s_Agreement iRODS] and [http://www.canonical.com/sites/default/files/active/images/Canonical-HA-CLA-ANY-I.pdf Ubuntu] (Canonical).

= Send us the code =

=== Via patch ===

If you are new in git, you may want to read about how to contribute to a project: http://git-scm.com/book/ch5-2.html, especially the section '''Public Large Project''' which explains how to use git format-patch to send properly formatted patches to our developers. The process, in brief, is:

# Clone or fork the [https://github.com/artefactual/atom AtoM github repository]
# Create a new local branch: <code>git checkout -b nicefeature</code>
# Write the code!
# Create a patch (or patches): <code>git format-patch -M origin/master</code>
# Paste the patch contents to a text file, and attach it to an email ''or'' use <code>git send-email</code>


Send your patches to: [mailto:ica-atom-users@googlegroups.com ica-atom-users@googlegroups.com.]

We prefer multiple small patches to a large patch that fixes multiple issues.

In recognition of your contribution, your name will be added to the list of [[Development/Contributors|Contributors]]. Fame and glory!

<admonition type="tip">
Please, follow these instructions when writing your commit messages:

* http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines
</admonition>

=== Via GitHub pull request ===

We also accept Github pull requests to our repository. Please see the GitHub help page on [https://help.github.com/articles/using-pull-requests Using pull requests] for more information.

Here are a few blog posts from around the web that offer more help and overviews using pull requests:

* The GitHub blog has a post on "how to write the perfect pull request" [https://github.com/blog/1943-how-to-write-the-perfect-pull-request here]
* The SpringSource community blog has useful posts on pull requests [http://blog.springsource.com/2010/12/21/social-coding-in-spring-projects/ here] and [http://blog.springsource.org/2011/07/18/social-coding-pull-requests-what-to-do-when-things-get-complicated/ here]
* Otaku, Cedric's Blog has a quick guide to pull requests [http://beust.com/weblog/2010/09/15/a-quick-guide-to-pull-requests/ here]

<admonition type="seealso">
* Information about the AtoM [[Resources/Code repository|Code repository]]
</admonition>

== Add License information to your patch ==

If you are making a bug fix or enhancement to an existing file, simply add your name as one of the authors in the file header. Here's an example:

<pre>
/**
 * Extended methods for information object model
 *
 * @package AccesstoMemory
 * @subpackage model
 * @author Peter Van Garderen <peter@artefactual.com>
 * @author David Juhasz <david@artefactual.com>
 * '''@author YourNameHere <youremail@address>'''
 */
</pre>

If you're contributing a new file, you need to add the following license header at the very top of the file. Copy both sections, in full, exactly as it is written here, filling in the information where indicated in bold,

<pre>
/*
 * This file is part of the Access to Memory (AtoM) software.
 *
 * Access to Memory (AtoM) is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * Access to Memory (AtoM) is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Access to Memory (AtoM).  If not, see <http://www.gnu.org/licenses/>.
 */
</pre>

<pre>
/**
 * '''description of what your new file does'''
 *
 * @package AccesstoMemory
 * @subpackage '''name of AtoM module or component to which your file contributes'''
 * '''@author YourNameHere <youremail@address>'''
 */
</pre>

=Code review=

With all contributions made to the AtoM project, whether via community pull request or from Artefactual developers, we always submit our code to a code review process, to make sure the code meets our coding standards, works as expected, is easy to understand, and remains consistent with other design principles used throughout the application.

* Find out more about our Code Review process here: [[Development/Code review|Code review]]
* Learn about our Coding standards here: [[Development/Coding standard|Coding standard]]

<admonition type="seealso">
* [[Resources/Code repository|Code repository]]
</admonition>


'''Thanks for contributing!'''

= Additional Resources =

* [https://groups.google.com/forum/#!forum/ica-atom-users AtoM User Forum]
* [https://projects.artefactual.com/projects/atom AtoM Project Page and Issue Tracker]
* [http://help.github.com/ General GitHub documentation]
* [https://github.com/artefactual/atom AtoM GitHub repository]
* [http://www.artefactual.com/ Artefactual Systems]


You can also chat with online AtoM project team members in our open IRC chat:
Channel: #openarchives (irc://#openarchives@irc.oftc.net)

The server address is irc.oftc.net, port 6667


[[#Development/Contribute code|Back to top]]


[[Category:Development documentation]]