Difference between revisions of "Contribute code"

From Archivematica
Jump to navigation Jump to search
(Update sphinx link)
 
(22 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 people who contribute have contributed regular patches 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==
 +
In order to accept any patches or code commits, contributors must first sign the [[Contributor Agreement|Archivematica Contributor's Agreement]].
 +
 
 +
==Standards==
 +
 
 +
=== Code Style Guide For Archivematica ===
 +
 
 +
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).
 +
* [https://www.python.org/dev/peps/pep-0008/ 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
 +
* [https://www.python.org/dev/peps/pep-0257/ PEP257] for docstring structure
 +
** Parameters and return values should be specified in [http://sphinx-doc.org/domains.html#info-field-lists Sphinx-style].
 +
* See also [https://github.com/artefactual/archivematica/pull/218 this pull request] and associated discussion.
 +
 
 +
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).
  
−
==Copyright and license==
+
    When iterating, makes two passes: first iterating over files, then
−
You will retain copyright as the original author of any code that you write and contribute to the Archivematica project. This is recognized in the [http://code.google.com/p/qubit-toolkit/source/browse/trunk/qubit/COPYRIGHT COPYRIGHT file] that is distributed with the Archivematica code. However, in order to integrate your code into Archivematica project, you need to release it under a GPL v2 license by following [[Copyright and license|these instructions]].
+
    directories. Does not iterate over directories; consumers should
 +
    call this function again on directory strings to recurse.
  
−
[[Subversion]]
+
    :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>
  
−
[[Build a virtual appliance]]
+
=== File Structure ===
 +
The file structure in Archivematica will comply with the Filesystem Hierarchy Standard (FHS). 
 +
<br/>More information on this standard is available at: 
 +
<br/>http://www.pathname.com/fhs/

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"