Difference between revisions of "Contribute code"
Jump to navigation
Jump to search
(→Code Style Guide For Archivematica: Update to reference external guidelines mostly) |
(Update sphinx link) |
||
| (5 intermediate revisions by one other user 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 | + | |
| + | 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== | ||
| Line 15: | Line 24: | ||
=== Code Style Guide For Archivematica === | === Code Style Guide For Archivematica === | ||
| − | Archivematica follows common Python coding standards, | + | 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 | * [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. | ** 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 | ** Imports are sorted alphabetically within their grouping to reduce duplicate imports | ||
* [https://www.python.org/dev/peps/pep-0257/ PEP257] for docstring structure | * [https://www.python.org/dev/peps/pep-0257/ PEP257] for docstring structure | ||
| − | ** Parameters and return values should be specified in Sphinx-style. | + | ** 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). | ||
| − | + | 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 18: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:
- 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[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/