diff --git a/docs/index.rst b/docs/index.rst --- a/docs/index.rst +++ b/docs/index.rst @@ -3,8 +3,60 @@ Software Heritage - Deposit =========================== -Push-based deposit of software source code artifacts to the archive. +Push-based deposit of software source code artifacts and metadata to the +Software Heritage (SWH) Archive. +Description +----------- + +Most of the software source code artifacts present in the SWH Archive are +gathered by the mean of :term:`loader ` workers run by the SWH project +from sourve code origins identified by :term:`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 :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 `reference the source code +`_ (e.g. in a `scientific paper +`_) +and retrieve it using the :ref:`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 artifacts 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 :ref:`getting-started` page for more details on how to use the deposit +client tools to push a deposit in the SWH Archive. + +.. _codemeta: https://codemeta.github.io/ +.. _`SWORD v2`: http://swordapp.org/sword-v2/ .. toctree:: :maxdepth: 2