Difference between revisions of "Contribute code"

From Archivematica
Jump to navigation Jump to search
(Update sphinx link)
 
(11 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
[[Main Page]] > [[Development]] > Contribute code
 
[[Main Page]] > [[Development]] > Contribute code
  
 +
Expanded contribution guidelines can also be found in the Archivematica [https://github.com/artefactual/archivematica/blob/qa/1.x/CONTRIBUTING.md contributing document].
 +
 +
[[Category:Process documentation]]
  
 
==Patches==
 
==Patches==
−
If you find a bug in this project or would like to make an enhancement, please be encouraged to contribute a patch by following [[Patches|these instructions]].
+
 
 +
If you find a bug in this project or would like to make an enhancement, please be encouraged to contribute code via a pull request.  Archivematica code is available on github. We will accept git pull requests from individuals who have submitted a [[Contributor Agreement]].
 +
 
 +
For more information please visit:
 +
* https://help.github.com/articles/creating-a-pull-request
 +
* https://help.github.com/articles/using-pull-requests
 +
* https://help.github.com/articles/fork-a-repo
  
 
==Commit access==
 
==Commit access==
−
Anyone can contribute code patches to this project. Project collaborators and regular patch contributors will be given access to commit directly to the [[Subversion]] code repository.
+
Anyone can contribute code patches to this project. Project collaborators and regular patch contributors will be given access to commit directly to the git code repository.
  
 
==Contributor's Agreement==
 
==Contributor's Agreement==
−
In order to accept any patches or code commits, contributors must first sign the [[Contributor Agreement|Archivematica 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 Archivematica copyrights through contributor agreements is the best way to protect the availability and sustainability of Archivematica 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 Archivematica, while enabling Artefactual Systems, any successor Foundation which may eventually take over responsibility for Archivematica, and the wider Archivematica community to benefit from their collaboration and contributions in this open source project.
+
In order to accept any patches or code commits, contributors must first sign the [[Contributor Agreement|Archivematica Contributor's Agreement]].
−
 
 
  
 
==Standards==
 
==Standards==
  
 
=== Code Style Guide For Archivematica ===
 
=== Code Style Guide For Archivematica ===
−
This coding convention is adopted from:
 
−
<br/>http://www.python.org/dev/peps/pep-0008/
 
−
<br/>authors: Guido van Rossum <guido at python.org>, Barry Warsaw <barry at python.org>
 
  
−
*Tabs are forbidden.
+
Archivematica follows common Python coding standards, linked below.  We encourage installing a Python [http://stackoverflow.com/questions/8503559/what-is-linting linter] to help with this. [https://pypi.python.org/pypi/flake8 flake8] is recommended because it wraps three common linters (pep8, pyflakes, mccabe).
−
*4 spaces per indent.
+
* [https://www.python.org/dev/peps/pep-0008/ PEP8] for styling
−
*cammelCase all variables, starting with lower case.
+
** Exception is line length, which should be wrapped at 79 characters or left long for the IDE to wrap.
−
*Max 79 characters per line.
+
** Imports are sorted alphabetically within their grouping to reduce duplicate imports
−
*Each import is on it's own line (no comma separated imports)
+
* [https://www.python.org/dev/peps/pep-0257/ PEP257] for docstring structure
−
*No spaces next to parenthesis '('
+
** Parameters and return values should be specified in [http://sphinx-doc.org/domains.html#info-field-lists Sphinx-style].
−
*No space before comma, space after comma.
+
* See also [https://github.com/artefactual/archivematica/pull/218 this pull request] and associated discussion.
−
*Assignments and comparators are given a single space separator 'x = 1'
+
 
 +
Example docstrings with Sphinx markup below. Other attributes that can be used in a docstring can be found [https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#python-signatures on the Sphinx website].
 +
 
 +
<pre>def get_unit_status(unit_uuid, unit_type):
 +
    """
 +
    Get status for a SIP or Transfer.
 +
 
 +
    Returns a dict with status info. Keys will always include 'status' and
 +
    'microservice', and may include 'sip_uuid'.
 +
 
 +
    Status is one of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING.
 +
    Microservice is the name of the current microservice.
 +
    SIP UUID is populated only if the unit_type was unitTransfer and status is
 +
    COMPLETE.  Otherwise, it is None.
 +
 
 +
    :param str unit_uuid: UUID of the SIP or Transfer
 +
    :param str unit_type: unitSIP or unitTransfer
 +
    :return: Dict with status info.
 +
    """</pre>
 +
 
 +
<pre>def each_child(path, file_group_identifier, base_path, base_path_name, sip_uuid):
 +
    """
 +
    Iterates over entries in a filesystem, beginning at `path`.
 +
 
 +
    At each entry in the filesystem, yields either a File model instance
 +
    (for files) or a string (for directories).
 +
 
 +
    When iterating, makes two passes: first iterating over files, then
 +
    directories. Does not iterate over directories; consumers should
 +
    call this function again on directory strings to recurse.
 +
 
 +
    :param string path: path to a directory on disk to recurse into.
 +
    :raises ValueError: if the specified path does not exist, or is not a directory.
 +
    """
 +
</pre>
  
 
=== File Structure ===
 
=== File Structure ===

Latest revision as of 17:32, 15 July 2020

Main Page > Development > Contribute code

Expanded contribution guidelines can also be found in the Archivematica contributing document.

Patches[edit]

If you find a bug in this project or would like to make an enhancement, please be encouraged to contribute code via a pull request. Archivematica code is available on github. We will accept git pull requests from individuals who have submitted a Contributor Agreement.

For more information please visit:

Commit access[edit]

Anyone can contribute code patches to this project. Project collaborators and regular patch contributors will be given access to commit directly to the git code repository.

Contributor's Agreement[edit]

In order to accept any patches or code commits, contributors must first sign the Archivematica Contributor's Agreement.

Standards[edit]

Code Style Guide For Archivematica[edit]

Archivematica follows common Python coding standards, linked below. We encourage installing a Python linter to help with this. flake8 is recommended because it wraps three common linters (pep8, pyflakes, mccabe).

  • PEP8 for styling
    • Exception is line length, which should be wrapped at 79 characters or left long for the IDE to wrap.
    • Imports are sorted alphabetically within their grouping to reduce duplicate imports
  • PEP257 for docstring structure
    • Parameters and return values should be specified in Sphinx-style.
  • See also this pull request and associated discussion.

Example docstrings with Sphinx markup below. Other attributes that can be used in a docstring can be found on the Sphinx website. 

def get_unit_status(unit_uuid, unit_type):
    """
    Get status for a SIP or Transfer.

    Returns a dict with status info.  Keys will always include 'status' and
    'microservice', and may include 'sip_uuid'.

    Status is one of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING.
    Microservice is the name of the current microservice.
    SIP UUID is populated only if the unit_type was unitTransfer and status is
    COMPLETE.  Otherwise, it is None.

    :param str unit_uuid: UUID of the SIP or Transfer
    :param str unit_type: unitSIP or unitTransfer
    :return: Dict with status info.
    """
def each_child(path, file_group_identifier, base_path, base_path_name, sip_uuid):
    """
    Iterates over entries in a filesystem, beginning at `path`.

    At each entry in the filesystem, yields either a File model instance
    (for files) or a string (for directories).

    When iterating, makes two passes: first iterating over files, then
    directories. Does not iterate over directories; consumers should
    call this function again on directory strings to recurse.

    :param string path: path to a directory on disk to recurse into.
    :raises ValueError: if the specified path does not exist, or is not a directory.
    """

File Structure[edit]

The file structure in Archivematica will comply with the Filesystem Hierarchy Standard (FHS).
More information on this standard is available at:
http://www.pathname.com/fhs/

Retrieved from "https://wiki.archivematica.org/index.php?title=Contribute_code&oldid=13503"