diff --git a/docs/index.rst b/docs/index.rst --- a/docs/index.rst +++ b/docs/index.rst @@ -5,6 +5,50 @@ Push-based deposit of software source code artifacts to the archive. +Description +----------- + +Most of the software source code artifacts present in the Software Heritage +Archive are gathered by the mean of :term:`loader ` workers run by the +Software Heritage project from sourve code origins identified by :term:`lister +` workers. This is a pull mechanism: it's the responsibility of the +Software Heritage project to gather and collect source code artifacts that +way. + +But there is also a push-based mechanism, allowing Software Heritage partners to +push their source code artifacts directly in the Archive (without having to do +so by the mean of an intermediate source code repository already known and +harvested, like github). + +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 +Software Heritage Archive. The result of that is a :ref:`SWHID +` that can be used to uniquely and persistently +identify that very piece of source code. + +This unique identifier can then be used to `cite the source code +`_ (e.g. in a `scientific paper +`_) and +retrieve it using the :ref:`vault ` feature of the Software Heritage +Archive platform. + +The differences between a piece of code uploaded using the deposit rather than +simply asking Software Heritage to archive a repository using the `save code +now `_ feature are: + +- a deposited artifact have codemeta_ metadata attached to it, +- a deposited artifact is linked to the deposit user with (some) trust, +- a deposit requires a metadata file describing the deposited artifact, +- the deposit API uses the `SWORD v2`_ API, thus requires some tooling to make + the deposit (which is provided with this repository). + +See the :ref:`getting-started` page for more details on how to use the deposit +client tools to push a deposit in the Software Heritage Archive. + +.. _codemeta: https://codemeta.github.io/ +.. _`SWORD v2`: http://swordapp.org/sword-v2/ .. toctree:: :maxdepth: 2