Difference between revisions of "Contribute code"

From Archivematica
Jump to navigation Jump to search
(Update sphinx link)
 
(10 intermediate revisions by 3 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==
Line 14: Line 23:
  
 
=== 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"