Difference between revisions of "Development/Contribute code"

From AtoM wiki
(Send us the code)
(Copyright and license: Add email address for sending contrib agreements)
 
(16 intermediate revisions by 4 users not shown)
Line 5: Line 5:
  
 
If you find a bug in this project or would like to make an enhancement, please contribute a patch and help us improve AtoM!
 
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">
 
<admonition type="seealso">
* Interested in contributing to our project documentation? We have a separate page for that! See:  https://accesstomemory.org/docs/about-contribute/
+
* See a list previous [[Community/Contributors|code contributors]]!
* Check out our wiki page about our code repository - includes helpful links and tips to get you started: [[Resources/Code repository]]
+
* Interested in contributing to our project documentation? We have a separate page for that! See:  [[Resources/Documentation/Contribute|Contribute documentation]]
 +
* Want to contribute translations for AtoM's user interface? See: [[Resources/Translation|Contribute translations]]
 +
* Check out our wiki page about our code repository - includes helpful links and tips to get you started: [[Resources/Code repository|Code repository]]
 
</admonition>
 
</admonition>
  
  
 
= Copyright and license =
 
= 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)]'''.
+
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 [mailto:agreement@artefactual.com agreement@artefactual.com].
  
 
===Why do I have to sign a Contributor's Agreement?===
 
===Why do I have to sign a Contributor's Agreement?===
Line 25: Line 34:
 
===Do you have examples of Contributor's Agreements from other projects?===
 
===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].
+
The AtoM contributor's agreement is based almost verbatim on the [http://apache.org Apache Foundation]'s individual [http://www.apache.org/licenses/icla.pdf 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).
+
Examples from other projects include:
 +
# [https://www.irods.org/index.php/iRODS_Contributor%E2%80%99s_Agreement iRODS]
 +
# [https://www.ubuntu.com/legal/contributors Ubuntu] (Canonical)
 +
# [https://wiki.duraspace.org/display/DSP/Contributor+License+Agreements Fedora 4 , DSpace Vivo] (DuraSpace)
 +
# [https://archivesspace.atlassian.net/wiki/display/ADC/How+to+Contribute+Code+or+Documentation ArchivesSpace] (ArchivesSpace)
 +
# [https://www.elastic.co/contributor-agreement ElasticSearch] (Elastic]
  
 
= Send us the code =
 
= Send us the code =
Line 46: Line 60:
 
We prefer multiple small patches to a large patch that fixes multiple issues.
 
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!
+
In recognition of your contribution, your name will be added to the list of [[Community/Contributors|Contributors]]. Fame and glory!
  
 
<admonition type="tip">
 
<admonition type="tip">
Please, follow these instructions when writing your commit messages:  
+
Please, follow these instructions when writing your commit messages:
  
 
* http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines
 
* http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines
Line 60: Line 74:
 
Here are a few blog posts from around the web that offer more help and overviews using pull requests:
 
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]
 
* 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]
 
* 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]
Line 66: Line 81:
 
* Information about the AtoM [[Resources/Code repository|Code repository]]
 
* Information about the AtoM [[Resources/Code repository|Code repository]]
 
</admonition>
 
</admonition>
 
  
 
== Add License information to your patch ==
 
== 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:  
+
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>
 
<pre>
Line 102: Line 116:
 
  * You should have received a copy of the GNU General Public License
 
  * 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/>.
 
  * along with Access to Memory (AtoM).  If not, see <http://www.gnu.org/licenses/>.
  */
+
  *
</pre>
 
 
 
<pre>
 
/**
 
 
  * '''description of what your new file does'''
 
  * '''description of what your new file does'''
 
  *
 
  *
Line 114: Line 124:
 
  */
 
  */
 
</pre>
 
</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!'''
 
'''Thanks for contributing!'''
Line 124: Line 146:
 
* [https://github.com/artefactual/atom AtoM GitHub repository]
 
* [https://github.com/artefactual/atom AtoM GitHub repository]
 
* [http://www.artefactual.com/ Artefactual Systems]
 
* [http://www.artefactual.com/ Artefactual Systems]
 +
* [[Community/Contributors|See who else has contributed to AtoM!]]
  
 +
-----
  
You can also chat with online AtoM project team members in our open IRC chat:
+
* [[Development|Back to Development]]
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]]
 
[[Category:Development documentation]]

Latest revision as of 14: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:

Seealso

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!

Tip

Please, follow these instructions when writing your commit messages:

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

Seealso

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.

Thanks for contributing!

Additional Resources