swh.deposit 3.0.0
Software Heritage deposit server
Requires Python: >=3.7

Software Heritage - Deposit
===========================

Simple Web-Service Offering Repository Deposit (S.W.O.R.D) is an interoperability
standard for digital file deposit.

This repository is both the `SWORD v2`_ Server and a deposit command-line client
implementations.

This implementation allows interaction between a client (a repository) and a server (SWH
repository) to deposit software source code archives and associated metadata.

Description
-----------

Most of the software source code artifacts present in the SWH Archive are gathered by
the mean of `loader`_ workers run by the SWH project from source code
origins identified by `lister`_ workers. This is a pull mechanism: it's
the responsibility of the SWH project to gather and collect source code artifacts that
way.

Alternatively, SWH allows its partners to push source code artifacts and metadata
directly into the Archive with a push-based mechanism. By using this possibility
different actors, holding software artifacts or metadata, can preserve their assets
without having to pass through an intermediate collaborative development platform, which
is already harvested by SWH (e.g GitHub, Gitlab, etc.).

This mechanism is the ``deposit``.

The main idea is the deposit is an authenticated access to an API allowing the user to
provide source code artifacts -- with metadata -- to be ingested in the SWH Archive. The
result of that is a `SWHID`_ that can be used to uniquely
and persistently identify that very piece of source code.

This unique identifier can then be used to `reference the source code
<https://hal.archives-ouvertes.fr/hal-02446202>`_ (e.g. in a `scientific paper
<https://www.softwareheritage.org/2020/05/26/citing-software-with-style/>`_) and
retrieve it using the `vault`_ feature of the SWH Archive platform.

The differences between a piece of code uploaded using the deposit rather than simply
asking SWH to archive a repository using the `save code now`_ feature
are:

- a deposited artifact is provided from one of the SWH partners which is regarded as a
  trusted authority,
- a deposited artifact requires metadata properties describing the source code artifact,
- a deposited artifact has a codemeta_ metadata entry attached to it,
- a deposited artifact has the same visibility on the SWH Archive than a collected
  repository,
- a deposited artifact can be searched with its provided url property on the SWH
  Archive,
- the deposit API uses the `SWORD v2`_ API, thus requires some tooling to send deposits
  to SWH. These tools are provided with this repository.


See the `User Manual`_ page for more details on how to use the deposit client
command line tools to push a deposit in the SWH Archive.

See the `API Documentation`_ reference pages of the SWORDv2 API implementation
in ``swh.deposit`` if you want to do upload deposits using HTTP requests.

Read the `Deposit metadata`_ chapter to get more details on what metadata
are supported when doing a deposit.

See `Running swh-deposit locally`_ if you want to hack the code of the ``swh.deposit`` module.

See `Production deployment`_ if you want to deploy your own copy of the
`swh.deposit` stack.


.. _codemeta: https://codemeta.github.io/
.. _SWORD v2: http://swordapp.org/sword-v2/
.. _loader: https://docs.softwareheritage.org/devel/glossary.html#term-loader
.. _lister: https://docs.softwareheritage.org/devel/glossary.html#term-lister
.. _SWHID: https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html#persistent-identifiers
.. _vault: https://docs.softwareheritage.org/devel/swh-vault/index.html#swh-vault
.. _save code now: https://archive.softwareheritage.org/save/
.. _User Manual: https://docs.softwareheritage.org/devel/swh-deposit/api/user-manual.html#deposit-user-manual
.. _API Documentation: https://docs.softwareheritage.org/devel/swh-deposit/api/api-documentation.html#deposit-api-specifications
.. _Deposit metadata: https://docs.softwareheritage.org/devel/swh-deposit/api/metadata.html#deposit-metadata
.. _Running swh-deposit locally: https://docs.softwareheritage.org/devel/swh-deposit/internals/dev-environment.html#swh-deposit-dev-env
.. _Production deployment: https://docs.softwareheritage.org/devel/swh-deposit/internals/prod-environment.html#swh-deposit-prod-env