Latest revision as of 13:57, 9 January 2018

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: Code review
• Learn about our Coding standards here: Coding standard
• Find information about our Code repository here: Code repository

Copyright and license

In order to accept any patches or code commits, contributors must first sign this contributor agreement (PDF): File:Accesstomemory-contributor-agreement-2014.pdf. You can send your signed copy of the Agreement to agreement@artefactual.com.

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.

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 Apache Foundation's individual contributor license.

Examples from other projects include:

1. iRODS
2. Ubuntu (Canonical)
3. Fedora 4 , DSpace Vivo (DuraSpace)
4. ArchivesSpace (ArchivesSpace)
5. ElasticSearch (Elastic]

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:

1. Clone or fork the AtoM github repository
2. Create a new local branch: git checkout -b nicefeature
3. Write the code!
4. Create a patch (or patches): git format-patch -M origin/master
5. Paste the patch contents to a text file, and attach it to an email or use git send-email

Send your patches to: 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 Contributors. Fame and glory!

Via GitHub pull request

We also accept Github pull requests to our repository. Please see the GitHub help page on 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" here
• The SpringSource community blog has useful posts on pull requests here and here
• Otaku, Cedric's Blog has a quick guide to pull requests here

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:

/**
 * 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>'''
 */

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,

/*
 * 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/>.
 *
 * '''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>'''
 */

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: Code review
• Learn about our Coding standards here: Coding standard

Thanks for contributing!

Additional Resources

• AtoM User Forum
• AtoM Project Page and Issue Tracker
• General GitHub documentation
• AtoM GitHub repository
• Artefactual Systems
• See who else has contributed to AtoM!

• Back to Development