diff --git a/docs/index.rst b/docs/index.rst
index af7ff6ff40d33a078d8f8232e8f767f19b653dcf..5fdf8e4f36d82696ae6ec74340e2c9dac9f6d485 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -218,6 +218,15 @@ Save a code repository
endpoint, GitHub endpoint, GitLab
endpoint <https://archive.softwareheritage.org/api/1/origin/save/doc/>`__
+Deposit artefacts and/or metadata
+---------------------------------
+
+The deposit service allows a trusted partner to submit software source archives and its
+associated metadata to the Software Heritage archive. Metadata can be also submitted referencing a repository url (origin) or a
+:ref:`SWHIDs <persistent-identifiers>`.
+
+:doc:`Discover the deposit service <user/deposit/index>`
+
Save multiple projects at a time, save a forge
----------------------------------------------
@@ -228,20 +237,8 @@ Save a forge in 2 steps :
2. `Submit a request of archival for to save a complete forge
<https://archive.softwareheritage.org/add-forge/request/create/>`__
-:ref:`Technical insight on the “Add forge now†process
-<save-forge>`
-
-Save code used for science
---------------------------
-
-Save a software using ELife, Ipol, HAL. Your content are directly pushed
-into the archive by trusted partners using the deposit service of
-Software Heritage:
+:ref:`Technical insight on the “Add forge now†process <save-forge>`
-- `Deposit software using the HAL
- portal <https://www.softwareheritage.org/2018/09/28/depositing-scientific-software-into-software-heritage/>`__
-- `Video tutorial on source code deposit using
- Hal <https://www.youtube.com/watch?v=-Ggn98sR3Eg&list=PLD2VqrZz2-u3bOWtoCoBIh5Flt6iYXsq3>`__
Save legacy source code
-----------------------
@@ -438,4 +435,4 @@ Table of contents
devel/api-reference
user/index
sysadm/index
- About this documentation project <README>
+ About <README>
diff --git a/docs/user/Makefile b/docs/user/Makefile
index a0c54493fa398d751237993ac5f71c4cbe384a61..f5fdbca845c187e85d16bcc5688f413c0de5157f 100644
--- a/docs/user/Makefile
+++ b/docs/user/Makefile
@@ -3,7 +3,7 @@
# You can set these variables from the command line, and also
# from the environment for the first two.
-SPHINXOPTS ?= -t sysadm_doc
+SPHINXOPTS ?= -t user_doc
SPHINXBUILD ?= sphinx-build
SOURCEDIR = .
BUILDDIR = _build
diff --git a/docs/user/deposit/explanations/deposit.rst b/docs/user/deposit/explanations/deposit.rst
new file mode 100644
index 0000000000000000000000000000000000000000..e43e39df213fe5f25aa9d22655cdb746730d41c2
--- /dev/null
+++ b/docs/user/deposit/explanations/deposit.rst
@@ -0,0 +1,62 @@
+What's a deposit?
+=================
+
+Most of the software source code artifacts present in the |swh| Archive are
+gathered by tools run by the SWH project, 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 trusted partners to send source code artifacts and/or
+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 result of this action is a :ref:`SWHID <persistent-identifiers>` 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 features of the SWH Archive platform.
+
+The differences between a deposit and simply asking SWH to archive a repository using the pull features of the Archive 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 can be searched with its provided url property on the SWH
+ Archive
+- it is possible to make a metadata only deposit only about an artefact already
+ present in the |swh| archive.
+
+Deposits are made using `SWORD v2`_, an interoperability standard for depositing
+content into repositories.
+
+.. _SWORD v2: https://sword.cottagelabs.com/previous-versions-of-sword/sword-v2/
+
+Metadata?
+---------
+
+The metadata of a software artefact is the real added value of the deposit service, it
+allows a partner to provide extrinsic information on a source code (details about the
+author and its affiliation, external ids, mention in a scientific publication, etc.)
+which are usually not present in the code itself (intrinsic metadata).
+
+Metadata is indexed by our search engine and provide new ways of finding content in the
+archive.
+
+To understand why metadata is so important to us please read :doc:`why-metadata`.
+
+Is it useful for me?
+--------------------
+
+You know software source code has an essential role in research and should be archived
+properly, alongside data and publications. Software that was built for research as part
+of the open science ecosystem should be archived, referenced, described and cited.
+
+When depositing in |swh| you can describe a software artifact properly with specific metadata properties and it will be safely saved in the universal software archive.
+
+Ready to use our deposit services?
+----------------------------------
+
+Start by :doc:`../howto/account`.
\ No newline at end of file
diff --git a/docs/user/deposit/explanations/examples.rst b/docs/user/deposit/explanations/examples.rst
new file mode 100644
index 0000000000000000000000000000000000000000..9515b2f328ff9b85a8c12153acdbc0f0281a7b13
--- /dev/null
+++ b/docs/user/deposit/explanations/examples.rst
@@ -0,0 +1,20 @@
+Real-world examples / integrations
+==================================
+
+HAL
+---
+
+.. thumbnail:: ../images/deposit-communication-SWHID-scenario-2.png
+
+| When depositing in HAL you can describe a software artifact properly with specific metadata properties and fetch export formats (e.g BibTeX .bib file) to facilitate citation. Furthermore the source code will be safely saved in the universal software archive, Software Heritage.
+
+https://www.softwareheritage.org/2023/04/04/swhid-deposit-hal/
+
+Zenodo
+------
+
+.. thumbnail:: ../images/Zenodo_SWH-1536x716.png
+
+| Here’s how it works: Code deposited in Zenodo is automatically archived in Software Heritage, the world’s largest software source code archive. Researchers get a Digital Object Identifier (DOI) for easy citation, while Software Heritage computes a Software Hash Identifier (SWHID) for ensuring the identification of the exact version that is used or mentioned, for reproducibility – a real code fingerprint. All of this takes place behind the scenes, streamlining the archiving process. Researchers can simply deposit code in Zenodo, and the rest is handled automatically.
+
+https://www.softwareheritage.org/2024/11/13/software-heritage-zenodo-integration/
diff --git a/docs/user/deposit/explanations/index.rst b/docs/user/deposit/explanations/index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..b039cb8aada8922982e76adedeab402e11b91f68
--- /dev/null
+++ b/docs/user/deposit/explanations/index.rst
@@ -0,0 +1,11 @@
+Explanations
+============
+
+Read more about the deposit principles and usages.
+
+.. toctree::
+ :maxdepth: 1
+
+ deposit.rst
+ why-metadata.rst
+ examples.rst
\ No newline at end of file
diff --git a/docs/user/deposit/explanations/why-metadata.rst b/docs/user/deposit/explanations/why-metadata.rst
new file mode 100644
index 0000000000000000000000000000000000000000..725c3126cfe2f043380e0ac3f46475624aa68074
--- /dev/null
+++ b/docs/user/deposit/explanations/why-metadata.rst
@@ -0,0 +1,30 @@
+Why do we need metadata?
+========================
+
+Metadata provides essential context and structure to digital resources, making them
+easily discoverable, understandable, reusable, and verifiable. It increases
+searchability, enables proper attribution and citation, ensures reproducibility of
+research, and preserves the long-term value and significance of resources.
+
+Metadata also supports interoperability between different platforms and systems,
+facilitates auditing through clear provenance and licensing information, and promotes
+collaboration and knowledge sharing within and across communities. For better
+interoperability, Software Heritage has chosen the CodeMeta vocabulary as the metadata
+standard used for deposit and indexing.
+
+Without metadata, valuable digital resources could quickly become inaccessible,
+misunderstood, or unusable.
+
+The deposit partner is responsible for the provided metadata, ensuring its accuracy,
+completeness, and compliance with established standards.
+
+External resources:
+
+- Deliverable D4.4: The Research Software MetaData (RSMD) guidelines is a comprehensive
+ set of guidelines aimed at enhancing the findability, accessibility,
+ interoperability, and reusability of research software artifacts. Gruenpeter, Granger
+ et al. (2024). https://doi.org/10.5281/zenodo.10786147
+- Deliverable D6.1 | Report on Standardisation and Curation of Software Metadata and
+ PIDs.: Gruenpeter, Granger et al. (2024). an implementation overview and roadmap of
+ the efforts achieved by infrastructures in the evolving European landscape of
+ research software. https://doi.org/10.5281/zenodo.14509418
diff --git a/docs/user/deposit/howto/account.rst b/docs/user/deposit/howto/account.rst
new file mode 100644
index 0000000000000000000000000000000000000000..ae7174177be3aaf038d567f7b7da998b28289407
--- /dev/null
+++ b/docs/user/deposit/howto/account.rst
@@ -0,0 +1,19 @@
+Request an account
+==================
+
+.. admonition:: Deposit partner agreement
+ :class: warning
+
+ Access to the deposit services is restricted to organizations who signed the deposit
+ partner agreement. To learn more about this agreement please write to
+ deposit@softwareheritage.org
+
+With the agreement signed you will be able to register an account on our
+`production <https://archive.softwareheritage.org/oidc/login/>`_ and
+`staging <https://webapp.staging.swh.network/oidc/login/>`_ instances.
+
+Once you have an account, you will get a set of access credentials as a login, a
+password and a collection name (identified as ``USERNAME``, ``PASSWORD`` and
+``COLLECTION`` in the remaining of this documentation).
+
+You are now ready to :doc:`prepare`.
diff --git a/docs/user/deposit/howto/first-deposit.rst b/docs/user/deposit/howto/first-deposit.rst
new file mode 100644
index 0000000000000000000000000000000000000000..887520174b47c8ba5e0dbdeac17ef57dcb60682b
--- /dev/null
+++ b/docs/user/deposit/howto/first-deposit.rst
@@ -0,0 +1,179 @@
+.. _deposit-first:
+
+Make a first code & metadata deposit
+====================================
+
+.. admonition:: API/CLI reference
+ :class: note
+
+ This page will help you make a deposit without getting into too much details,
+ the :doc:`API reference <../references/api>` and the
+ :doc:`CLI reference <../references/cli>`
+ are available to explain all the technical specifications.
+
+Checklist
+---------
+
+- You have access to your :doc:`account credentials <account>`
+- You have a software artefact at hand and its associated metadata (if not you need to
+ :doc:`prepare your artefacts and metadata <prepare>`.)
+- This is the first time you're depositing for this origin (if you already made
+ deposits for this origin you want to
+ :doc:`make a new deposit for an existing origin <versions>`)
+- The software artefact is not larger than 100Mo (if not you need to
+ :doc:`make a multi-step deposit <multistep-deposit>`)
+- You have either the CLI installed or a tool to make API calls, we will use curl
+ here, but commands could be easily adapted to another application
+
+Send the artefact and the metadata
+----------------------------------
+
+.. admonition:: Deposit instance URL
+ :class: warning
+
+ In the examples below the staging deposit url https://deposit.staging.swh.network
+ is used to avoid experimenting on the production instance of the deposit server.
+ Make sure you switch to https://deposit.softwareheritage.org when you are ready.
+
+.. tab-set::
+
+ .. tab-item:: API
+
+ Note the ``In-Progress: false`` header. Also make sure the mimetype matches your
+ file, here ``SOFTWARE_ARTEFACT`` is a zip archive.
+
+ .. code-block:: console
+
+ curl -i -u USERNAME:PASSWORD \
+ -F "file=@SOFTWARE_ARTEFACT;type=application/zip;filename=payload" \
+ -F "atom=@METADATA_FILE;type=application/atom+xml;charset=UTF-8" \
+ -H 'In-Progress: false' \
+ -XPOST https://deposit.staging.swh.network/1/COLLECTION/
+
+ .. tab-item:: CLI
+
+ Note the '--no-partial' flag.
+
+ .. code-block:: console
+
+ swh deposit upload \
+ --username USERNAME --password PASSWORD \
+ --url https://deposit.staging.swh.network/1 \
+ --archive SOFTWARE_ARTEFACT \
+ --metadata METADATA_FILE \
+ --no-partial \
+ --format json
+
+Will return the following response (note the ``deposited`` status):
+
+.. tab-set::
+
+ .. tab-item:: API
+
+ .. code-block:: xml
+
+ <entry xmlns="http://www.w3.org/2005/Atom"
+ xmlns:sword="http://purl.org/net/sword/"
+ xmlns:dcterms="http://purl.org/dc/terms/"
+ xmlns:swhdeposit="https://www.softwareheritage.org/schema/2018/deposit"
+ >
+ <swhdeposit:deposit_id>DEPOSIT_ID</swhdeposit:deposit_id>
+ <swhdeposit:deposit_date>Jan. 1, 2025, 09:00 a.m.</swhdeposit:deposit_date>
+ <swhdeposit:deposit_archive>None</swhdeposit:deposit_archive>
+ <swhdeposit:deposit_status>deposited</swhdeposit:deposit_status>
+
+ <!-- Edit-IRI -->
+ <link rel="edit" href="/1/COLLECTION/DEPOSIT_ID/metadata/" />
+ <!-- EM-IRI -->
+ <link rel="edit-media" href="/1/COLLECTION/DEPOSIT_ID/media/"/>
+ <!-- SE-IRI -->
+ <link rel="http://purl.org/net/sword/terms/add" href="/1/COLLECTION/DEPOSIT_ID/metadata/" />
+ <!-- State-IRI -->
+ <link rel="alternate" href="/1/COLLECTION/DEPOSIT_ID/status/"/>
+
+ <sword:packaging>http://purl.org/net/sword/package/SimpleZip</sword:packaging>
+ </entry>
+
+ .. tab-item:: CLI
+
+ .. code-block:: json
+
+ {
+ "deposit_status": "deposited",
+ "deposit_id": "DEPOSIT_ID",
+ "deposit_date": "Jan. 1, 2025, 09:00 a.m.",
+ "deposit_status_detail": null
+ }
+
+A ``deposited`` status means the deposit is complete but still needs to be checked to
+ensure data consistency before it gets integrated in the archive. You can check your
+deposit status to follow the process.
+
+Check a deposit status and get its SWHID
+----------------------------------------
+
+Your deposit will go :doc:`through multiple steps <../references/workflow>` before appearing in the archive, you can check the status of your deposit and get its SWHID:
+
+.. tab-set::
+
+ .. tab-item:: API
+
+ .. code-block:: console
+
+ curl -i -u USERNAME:PASSWORD \
+ -XGET https://deposit.staging.swh.network/1/COLLECTION/DEPOSIT_ID/status/
+
+ .. tab-item:: CLI
+
+ .. code-block:: console
+
+ swh deposit status \
+ --username USERNAME --password PASSWORD \
+ --url https://deposit.staging.swh.network/1 \
+ --deposit-id DEPOSIT_ID \
+ --format json
+
+Will return the following response:
+
+.. tab-set::
+
+ .. tab-item:: API
+
+ .. code-block:: xml
+
+ <entry xmlns="http://www.w3.org/2005/Atom"
+ xmlns:sword="http://purl.org/net/sword/"
+ xmlns:dcterms="http://purl.org/dc/terms/"
+ xmlns:swhdeposit="https://www.softwareheritage.org/schema/2018/deposit"
+ >
+ <swhdeposit:deposit_id>DEPOSIT_ID</swhdeposit:deposit_id>
+ <swhdeposit:deposit_status>done</swhdeposit:deposit_status>
+ <swhdeposit:deposit_status_detail>The deposit has been successfully loaded into the Software Heritage archive</swhdeposit:deposit_status_detail>
+ <swhdeposit:deposit_swh_id>SWHID</swhdeposit:deposit_swh_id>
+ <swhdeposit:deposit_swh_id_context>SWHID_CONTEXT</swhdeposit:deposit_swh_id>
+ </entry>
+
+ .. tab-item:: CLI
+
+ .. code-block:: json
+
+ {
+ "deposit_id": "DEPOSIT_ID",
+ "deposit_status": "done",
+ "deposit_swh_id": "SWHID",
+ "deposit_swh_id_context": "SWHID_CONTEXT",
+ "deposit_status_detail": "The deposit has been successfully loaded into the Software Heritage archive"
+ }
+
+A ``done`` status means the deposit is now integrated in the archive, so you can
+access ``https://archive.softwareheritage.org/SWHID``,
+``https://archive.softwareheritage.org/SWHID_CONTEXT``, or
+``https://archive.softwareheritage.org/browse/origin/?origin_url=ORIGIN_URL`` to view
+the result of it.
+
+What's next ?
+-------------
+
+Now that you've made your first deposit you might want to
+:doc:`integrate it in your website <integrations>` or
+:doc:`push another version of the software <versions>`.
\ No newline at end of file
diff --git a/docs/user/deposit/howto/index.rst b/docs/user/deposit/howto/index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..8a307507304595fcc59635a071638223a4331b65
--- /dev/null
+++ b/docs/user/deposit/howto/index.rst
@@ -0,0 +1,16 @@
+How to guides
+=============
+
+To assist informed users with their deposits.
+
+.. toctree::
+ :maxdepth: 1
+
+ account.rst
+ prepare.rst
+ first-deposit.rst
+ multistep-deposit.rst
+ metadata-deposit.rst
+ versions.rst
+ integrations.rst
+ support.rst
\ No newline at end of file
diff --git a/docs/user/deposit/howto/integrations.rst b/docs/user/deposit/howto/integrations.rst
new file mode 100644
index 0000000000000000000000000000000000000000..c32cd7aee2c73f531b6111fd3e3c2c65a7f20533
--- /dev/null
+++ b/docs/user/deposit/howto/integrations.rst
@@ -0,0 +1,64 @@
+.. _deposit-integrations:
+
+Integrate a deposit to your website
+===================================
+
+There are multiple ways to integrate information about the artefact you deposited to
+the archive using the SWHID you obtained in return.
+
+Generate a badge
+----------------
+
+To generate a |swh| badge for a given object SWHID, for example
+``swh:1:dir:a5ceced7711d5043da4be6af76749ff638f93909;origin=https://doi.org/10.5281/zenodo.13375878;visit=swh:1:snp:5f88ed08d3cc491a0aab6c41b5591b9119d0d1bf;anchor=swh:1:rel:c5b2d34a22d8bb5cf3ac3d64f84bb0a000278e00``:
+
+.. tab-set::
+
+ .. tab-item:: HTML
+
+ .. code-block:: html
+
+ <a href="https://archive.softwareheritage.org/swh:1:dir:a5ceced7711d5043da4be6af76749ff638f93909;origin=https://doi.org/10.5281/zenodo.13375878;visit=swh:1:snp:5f88ed08d3cc491a0aab6c41b5591b9119d0d1bf;anchor=swh:1:rel:c5b2d34a22d8bb5cf3ac3d64f84bb0a000278e00">
+ <img src="https://archive.softwareheritage.org/badge/directory/a5ceced7711d5043da4be6af76749ff638f93909/" alt="Archived | swh:1:dir:a5ceced7711d5043da4be6af76749ff638f93909"/>
+ </a>
+
+ .. tab-item:: Markdown
+
+ .. code-block:: markdown
+
+ [](https://archive.softwareheritage.org/swh:1:dir:a5ceced7711d5043da4be6af76749ff638f93909;origin=https://doi.org/10.5281/zenodo.13375878;visit=swh:1:snp:5f88ed08d3cc491a0aab6c41b5591b9119d0d1bf;anchor=swh:1:rel:c5b2d34a22d8bb5cf3ac3d64f84bb0a000278e00)
+
+ .. tab-item:: reStructuredText
+
+ .. code-block:: rst
+
+ .. image:: https://archive.softwareheritage.org/badge/swh:1:dir:a5ceced7711d5043da4be6af76749ff638f93909/
+ :target: https://archive.softwareheritage.org/swh:1:dir:a5ceced7711d5043da4be6af76749ff638f93909;origin=https://doi.org/10.5281/zenodo.13375878;visit=swh:1:snp:5f88ed08d3cc491a0aab6c41b5591b9119d0d1bf;anchor=swh:1:rel:c5b2d34a22d8bb5cf3ac3d64f84bb0a000278e00
+
+You will obtain the following rendering:
+
+.. image:: https://archive.softwareheritage.org/badge/swh:1:dir:a5ceced7711d5043da4be6af76749ff638f93909/
+ :target: https://archive.softwareheritage.org/swh:1:dir:a5ceced7711d5043da4be6af76749ff638f93909;origin=https://doi.org/10.5281/zenodo.13375878;visit=swh:1:snp:5f88ed08d3cc491a0aab6c41b5591b9119d0d1bf;anchor=swh:1:rel:c5b2d34a22d8bb5cf3ac3d64f84bb0a000278e00
+
+Integrate an iframe
+-------------------
+
+A subset of Software Heritage objects (contents and directories) can be embedded in
+external websites through the use of iframes_. A dedicated endpoint serving a
+minimalist Web UI is available for that use case. Use this HTML code to do so:
+
+.. code-block:: html
+
+ <iframe style="width: 100%; height: 500px; border: 1px solid rgba(0, 0, 0, 0.125);"
+ src="https://archive.softwareheritage.org/browse/embed/swh:1:dir:a5ceced7711d5043da4be6af76749ff638f93909;origin=https://doi.org/10.5281/zenodo.13375878;visit=swh:1:snp:5f88ed08d3cc491a0aab6c41b5591b9119d0d1bf;anchor=swh:1:rel:c5b2d34a22d8bb5cf3ac3d64f84bb0a000278e00/">
+ </iframe>
+
+You will obtain the following rendering:
+
+.. raw:: html
+
+ <iframe style="width: 100%; height: 500px; border: 1px solid rgba(0, 0, 0, 0.125);"
+ src="https://archive.softwareheritage.org/browse/embed/swh:1:dir:a5ceced7711d5043da4be6af76749ff638f93909;origin=https://doi.org/10.5281/zenodo.13375878;visit=swh:1:snp:5f88ed08d3cc491a0aab6c41b5591b9119d0d1bf;anchor=swh:1:rel:c5b2d34a22d8bb5cf3ac3d64f84bb0a000278e00/">
+ </iframe>
+
+.. _iframes: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe
\ No newline at end of file
diff --git a/docs/user/deposit/howto/metadata-deposit.rst b/docs/user/deposit/howto/metadata-deposit.rst
new file mode 100644
index 0000000000000000000000000000000000000000..d889e55e217d9fdcce703311e8f89388be107bd0
--- /dev/null
+++ b/docs/user/deposit/howto/metadata-deposit.rst
@@ -0,0 +1,84 @@
+Make a metadata-only deposit
+============================
+
+.. admonition:: API/CLI reference
+ :class: note
+
+ This page will help you make a deposit without getting into too much details,
+ the :doc:`API reference <../references/api>` and the
+ :doc:`CLI reference <../references/cli>`
+ are available to explain all the technical specifications.
+
+It’s possible to deposit metadata on an already existing content using the
+metadata-only deposit and referencing a repository or a specific artifact.
+
+Checklist
+---------
+
+- You have access to your :doc:`account credentials <account>`
+- You have prepared your metadata (if not you need to
+ :doc:`prepare your artefacts and metadata <prepare>`.)
+- You have either the CLI installed or a tool to make API calls, we will use curl
+ here, but commands could be easily adapted to another application
+
+Make a metadata deposit
+-----------------------
+
+.. tab-set::
+
+ .. tab-item:: API
+
+ Note the ``In-Progress: false`` header as metadata-only deposits can only be done
+ in one-shot.
+
+ .. code-block:: console
+
+ curl -i -u <username>:<pass> \
+ -F "atom=@<metadatafile>;type=application/atom+xml;charset=UTF-8" \
+ -H 'In-Progress: false' \
+ -XPOST https://deposit.softwareheritage.org/1/<collection>/
+
+ .. tab-item:: CLI
+
+ .. code-block:: console
+
+ swh deposit metadata-only
+ --username <user> --password <pass> \
+ --url https://deposit.staging.swh.network/1 \
+ --metadata <metadatafile> \
+ --format json
+
+
+Will return the following response:
+
+.. tab-set::
+
+ .. tab-item:: API
+
+ .. code-block:: xml
+
+ <entry xmlns="http://www.w3.org/2005/Atom"
+ xmlns:sword="http://purl.org/net/sword/"
+ xmlns:dcterms="http://purl.org/dc/terms/"
+ xmlns:swhdeposit="https://www.softwareheritage.org/schema/2018/deposit"
+ >
+ <swhdeposit:deposit_id>DEPOSIT_ID</swhdeposit:deposit_id>
+ <swhdeposit:deposit_status>done</swhdeposit:deposit_status>
+ <swhdeposit:deposit_status_detail>The deposit has been successfully loaded into the Software Heritage archive</swhdeposit:deposit_status_detail>
+ <swhdeposit:deposit_swh_id>SWHID</swhdeposit:deposit_swh_id>
+ <swhdeposit:deposit_swh_id_context>SWHID_CONTEXT</swhdeposit:deposit_swh_id>
+ </entry>
+
+ .. tab-item:: CLI
+
+ .. code-block:: json
+
+ {
+ "deposit_id": "DEPOSIT_ID",
+ "deposit_status": "done",
+ "deposit_swh_id": "SWHID",
+ "deposit_swh_id_context": "SWHID_CONTEXT",
+ "deposit_status_detail": "The deposit has been successfully loaded into the Software Heritage archive"
+ }
+
+A ``done`` status means the metadata-only deposit is now integrated in the archive.
\ No newline at end of file
diff --git a/docs/user/deposit/howto/multistep-deposit.rst b/docs/user/deposit/howto/multistep-deposit.rst
new file mode 100644
index 0000000000000000000000000000000000000000..129bf89156e15279424901657d8b04964794c94f
--- /dev/null
+++ b/docs/user/deposit/howto/multistep-deposit.rst
@@ -0,0 +1,300 @@
+Make a multi-step code & metadata deposit
+=========================================
+
+.. admonition:: API/CLI reference
+ :class: note
+
+ This page will help you make a deposit without getting into too much details,
+ the :doc:`API reference <../references/api>` and the
+ :doc:`CLI reference <../references/cli>`
+ are available to explain all the technical specifications.
+
+.. admonition:: Partial deposits
+ :class: note
+
+ This method of depositing artefacts to the archive is a bit more complicated than
+ the other one, if your artefacts are not larger than 100Mo we would recommend
+ sticking to :doc:`the simpler (one shot) method <first-deposit>`.
+
+If you have multiple code artefacts or if you need to make your deposit in two or
+more times, you can make use of the partial deposit functionality.
+
+Checklist
+---------
+
+- You have access to your :doc:`account credentials <account>`
+- You have a software artefact at hand and its associated metadata (if not you need to
+ :doc:`prepare your artefacts and metadata <prepare>`.)
+- This is the first time you're depositing for this origin (if you already made
+ deposits for this origin you want to
+ :doc:`make a new deposit for an existing origin <versions>`)
+- You have either the CLI installed or a tool to make API calls, we will use curl
+ here, but commands could be easily adapted to another application
+
+Make the deposit in multiple steps
+----------------------------------
+
+.. admonition:: Deposit instance URL
+ :class: warning
+
+ In the examples below the staging deposit url https://deposit.staging.swh.network
+ is used to avoid experimenting on the production instance of the deposit server.
+ Make sure you switch to https://deposit.softwareheritage.org when you are ready.
+
+In the example below we will make a first deposit with a code artefact then a second
+one and finally a third one with the metadata.
+
+First partial deposit
+~~~~~~~~~~~~~~~~~~~~~
+
+.. tab-set::
+
+ .. tab-item:: API
+
+ Note the ``In-Progress: true`` header. Also make sure the mimetype matches your
+ file, here ``SOFTWARE_ARTEFACT1`` is a zip archive.
+
+ .. code-block:: console
+
+ curl -i -u USERNAME:PASSWORD \
+ -F "file=@SOFTWARE_ARTEFACT1;type=application/zip;filename=payload" \
+ -H 'In-Progress: true' \
+ -XPOST https://deposit.staging.swh.network/1/COLLECTION/
+
+ .. tab-item:: CLI
+
+ Note the '--partial' flag '--archive' argument, as we're sending a new software
+ artefact.
+
+ .. code-block:: console
+
+ swh deposit upload \
+ --username USERNAME --password PASSWORD \
+ --url https://deposit.staging.swh.network/1 \
+ --archive SOFTWARE_ARTEFACT1 \
+ --partial \
+ --format json
+
+Will return the following response (note the ``partial`` status and the ``deposit_id``
+value):
+
+.. tab-set::
+
+ .. tab-item:: API
+
+ .. code-block:: xml
+
+ <entry xmlns="http://www.w3.org/2005/Atom"
+ xmlns:sword="http://purl.org/net/sword/"
+ xmlns:dcterms="http://purl.org/dc/terms/"
+ xmlns:swhdeposit="https://www.softwareheritage.org/schema/2018/deposit"
+ >
+ <swhdeposit:deposit_id>DEPOSIT_ID</swhdeposit:deposit_id>
+ <swhdeposit:deposit_date>Jan. 1, 2025, 09:00 a.m.</swhdeposit:deposit_date>
+ <swhdeposit:deposit_archive>None</swhdeposit:deposit_archive>
+ <swhdeposit:deposit_status>partial</swhdeposit:deposit_status>
+
+ <!-- Edit-IRI -->
+ <link rel="edit" href="/1/COLLECTION/DEPOSIT_ID/metadata/" />
+ <!-- EM-IRI -->
+ <link rel="edit-media" href="/1/COLLECTION/DEPOSIT_ID/media/"/>
+ <!-- SE-IRI -->
+ <link rel="http://purl.org/net/sword/terms/add" href="/1/COLLECTION/DEPOSIT_ID/metadata/" />
+ <!-- State-IRI -->
+ <link rel="alternate" href="/1/COLLECTION/DEPOSIT_ID/status/"/>
+
+ <sword:packaging>http://purl.org/net/sword/package/SimpleZip</sword:packaging>
+ </entry>
+
+ .. tab-item:: CLI
+
+ .. code-block:: json
+
+ {
+ "deposit_status": "partial",
+ "deposit_id": "DEPOSIT_ID",
+ "deposit_date": "Jan. 1, 2025, 09:00 a.m.",
+ "deposit_status_detail": null
+ }
+
+Second partial deposit
+~~~~~~~~~~~~~~~~~~~~~~
+
+Instead of creating a new deposit we'll update the previous one referenced by
+``DEPOSIT_ID``. In our example, we're making this deposit in three steps, so we will
+indicate in our calls that this deposit is still ``partial``. The number of steps
+does not matter, the only important thing is to make all calls ``partial`` except the
+last one.
+
+.. tab-set::
+
+ .. tab-item:: API
+
+ Note the ``In-Progress: true`` header, the ``DEPOSIT_ID`` in the URL and the
+ ``/media/`` endpoint as we're sending a new software artefact.
+ Also make sure the mimetype matches your file, here ``SOFTWARE_ARTEFACT2`` is a
+ tarball.
+
+ .. code-block:: console
+
+ curl -i -u USERNAME:PASSWORD \
+ -F "file=@SOFTWARE_ARTEFACT2;type=application/x-tar;filename=payload" \
+ -H 'In-Progress: true' \
+ -XPOST https://deposit.staging.swh.network/1/COLLECTION/DEPOSIT_ID/media/
+
+ .. tab-item:: CLI
+
+ Note the '--partial' flag, the `--deposit-id` argument and the '--archive'
+ argument, as we're sending a new software artefact.
+
+ .. code-block:: console
+
+ swh deposit upload \
+ --username USERNAME --password PASSWORD \
+ --url https://deposit.staging.swh.network/1 \
+ --archive SOFTWARE_ARTEFACT2 \
+ --deposit-id DEPOSIT_ID \
+ --partial \
+ --format json
+
+This will return a response similar to the previous one.
+
+Third (and last) partial deposit
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This deposit will only consist of the metadata. To indicate this is the last step we
+will send include "not partial anymore" parameter in our call.
+
+.. tab-set::
+
+ .. tab-item:: API
+
+ Note the ``In-Progress: false`` header, the ``DEPOSIT_ID`` in the URL and the
+ ``/metadata/`` as we're pushing only metadata.
+
+ .. code-block:: console
+
+ curl -i -u USERNAME:PASSWORD \
+ -F "atom=@METADATA_FILE;type=application/atom+xml;charset=UTF-8" \
+ -H 'In-Progress: false' \
+ -XPOST https://deposit.staging.swh.network/1/COLLECTION/DEPOSIT_ID/metadata/
+
+ .. tab-item:: CLI
+
+ Note the '--not-partial' flag, the `--deposit-id` argument and the '--metadata'
+ argument, as we're pushing only metadata.
+
+ .. code-block:: console
+
+ swh deposit upload \
+ --username USERNAME --password PASSWORD \
+ --url https://deposit.staging.swh.network/1 \
+ --metadata METADATA_FILE \
+ --deposit-id DEPOSIT_ID \
+ --not-partial \
+ --format json
+
+
+Check a deposit status
+----------------------
+
+Your deposit will go :doc:`through multiple steps <../references/workflow>` before appearing in the archive, you can check the status of your deposit and get its SWHID:
+
+.. tab-set::
+
+ .. tab-item:: API
+
+ .. code-block:: console
+
+ curl -i -u USERNAME:PASSWORD \
+ -XGET https://deposit.staging.swh.network/1/COLLECTION/DEPOSIT_ID/status/
+
+ .. tab-item:: CLI
+
+ .. code-block:: console
+
+ swh deposit status \
+ --username USERNAME --password PASSWORD \
+ --url https://deposit.staging.swh.network/1 \
+ --deposit-id DEPOSIT_ID \
+ --format json
+
+Will return the following response:
+
+.. tab-set::
+
+ .. tab-item:: API
+
+ .. code-block:: xml
+
+ <entry xmlns="http://www.w3.org/2005/Atom"
+ xmlns:sword="http://purl.org/net/sword/"
+ xmlns:dcterms="http://purl.org/dc/terms/"
+ xmlns:swhdeposit="https://www.softwareheritage.org/schema/2018/deposit"
+ >
+ <swhdeposit:deposit_id>DEPOSIT_ID</swhdeposit:deposit_id>
+ <swhdeposit:deposit_status>done</swhdeposit:deposit_status>
+ <swhdeposit:deposit_status_detail>The deposit has been successfully loaded into the Software Heritage archive</swhdeposit:deposit_status_detail>
+ <swhdeposit:deposit_swh_id>SWHID</swhdeposit:deposit_swh_id>
+ <swhdeposit:deposit_swh_id_context>SWHID_CONTEXT</swhdeposit:deposit_swh_id>
+ </entry>
+
+ .. tab-item:: CLI
+
+ .. code-block:: json
+
+ {
+ "deposit_id": "DEPOSIT_ID",
+ "deposit_status": "done",
+ "deposit_swh_id": "SWHID",
+ "deposit_swh_id_context": "SWHID_CONTEXT",
+ "deposit_status_detail": "The deposit has been successfully loaded into the Software Heritage archive"
+ }
+
+A ``deposited`` status means the deposit is complete but still needs to be checked to
+ensure data consistency. You can check your deposit status to follow the process.
+
+Repeat the same calls until the status changes:
+
+.. tab-set::
+
+ .. tab-item:: API
+
+ .. code-block:: xml
+
+ <entry xmlns="http://www.w3.org/2005/Atom"
+ xmlns:sword="http://purl.org/net/sword/"
+ xmlns:dcterms="http://purl.org/dc/terms/"
+ xmlns:swhdeposit="https://www.softwareheritage.org/schema/2018/deposit"
+ >
+ <swhdeposit:deposit_id>DEPOSIT_ID</swhdeposit:deposit_id>
+ <swhdeposit:deposit_status>done</swhdeposit:deposit_status>
+ <swhdeposit:deposit_status_detail>The deposit has been successfully loaded into the Software Heritage archive</swhdeposit:deposit_status_detail>
+ <swhdeposit:deposit_swh_id>SWHID</swhdeposit:deposit_swh_id>
+ <swhdeposit:deposit_swh_id_context>SWHID_CONTEXT</swhdeposit:deposit_swh_id>
+ </entry>
+
+ .. tab-item:: CLI
+
+ .. code-block:: json
+
+ {
+ "deposit_id": "DEPOSIT_ID",
+ "deposit_status": "done",
+ "deposit_swh_id": "SWHID",
+ "deposit_swh_id_context": "SWHID_CONTEXT",
+ "deposit_status_detail": "The deposit has been successfully loaded into the Software Heritage archive"
+ }
+
+A ``done`` status means the deposit is now integrated in the archive, so you can
+access ``https://deposit.staging.swh.network/SWHID``,
+``https://deposit.staging.swh.network/SWHID_CONTEXT``, or
+``https://deposit.staging.swh.network/browse/origin/?origin_url=ORIGIN_URL`` to view
+the result of it.
+
+What's next ?
+-------------
+
+Now that you've made your first deposit you might want to
+:doc:`integrate it in your website <integrations>` or
+:doc:`push another version of the software <versions>`.
diff --git a/docs/user/deposit/howto/prepare.rst b/docs/user/deposit/howto/prepare.rst
new file mode 100644
index 0000000000000000000000000000000000000000..df552246213421286f55494295c4b24adf104b6f
--- /dev/null
+++ b/docs/user/deposit/howto/prepare.rst
@@ -0,0 +1,273 @@
+Prepare your metadata and artifacts
+===================================
+
+.. admonition:: Protocol reference
+ :class: note
+
+ This page will help you prepare a deposit without getting into too much details,
+ a :doc:`complete reference of the deposit protocol <../references/protocol>`
+ is also available to explain all the technical specifications.
+
+A deposit is constituted of a metadata file and optionally one or more software
+artefacts.
+
+The metadata file
+-----------------
+
+This is the most important part of a deposit process, see
+:doc:`../explanations/why-metadata`.
+
+Here's a complete metadata file example for a metadata-only deposit on ``ORIGIN_URL``:
+
+.. code-block:: xml
+
+ <?xml version="1.0" encoding="utf-8"?>
+
+ <!-- XML Entry -->
+ <entry xmlns="http://www.w3.org/2005/Atom"
+ xmlns:codemeta="https://doi.org/10.5063/schema/codemeta-2.0"
+ xmlns:swh="https://www.softwareheritage.org/schema/2018/deposit">
+
+ <!-- SWH deposit's own properties -->
+ <swh:deposit>
+ <swh:reference>
+ <swh:object swhid="SWHID_CONTEXT"/>
+ </swh:reference>
+
+ <!-- Metadata provenance -->
+ <swh:metadata-provenance>
+ <schema:url>METADATA_URL</schema:url>
+ </swh:metadata-provenance>
+ </swh:deposit>
+
+ <!-- CodeMeta metadata -->
+ <codemeta:name>A required software name</codemeta:name>
+ <codemeta:description>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus aliquam tincidunt lacus, ut mollis tellus volutpat a. Mauris ut ornare mauris. Suspendisse elementum lacinia erat, at ornare lorem fringilla vel. Aliquam sagittis dictum cursus. Etiam ut porta libero, ut malesuada augue. In viverra felis justo, a ullamcorper sem consectetur sed. Sed in euismod nunc.</codemeta:description>
+ <codemeta:dateCreated>2022-11-17</codemeta:dateCreated>
+ <codemeta:datePublished>2023-04-27</codemeta:datePublished>
+ <codemeta:license>
+ <codemeta:name>GNU Affero General Public License</codemeta:name>
+ </codemeta:license>
+ <codemeta:keywords>digital geometry,image processing,geometry processing</codemeta:keywords>
+ <codemeta:relatedLink>https://example.com</codemeta:relatedLink>
+ <codemeta:programmingLanguage>c++</codemeta:programmingLanguage>
+ <codemeta:operatingSystem>Linux, Mac OS X, Windows</codemeta:operatingSystem>
+ <codemeta:license>
+ <codemeta:name>GNU Affero General Public License</codemeta:name>
+ </codemeta:license>
+ <codemeta:author>
+ <codemeta:name>Hedy Lamarr</codemeta:name>
+ <codemeta:email>email@example.com</codemeta:email>
+ </codemeta:author>
+
+ <!-- Versioning info -->
+ <codemeta:version>1.0.0</codemeta:version>
+ </entry>
+
+This file can be a bit daunting, let's examine its content in detail.
+
+XML Entry
+~~~~~~~~~
+
+.. admonition:: CodeMeta versions
+ :class: warning
+
+ For now, the repository server is only compatible with CodeMeta v2, we will soon move to v3 which will become the recommended version.
+
+As we're using the SWORD v2 standard to handle the deposits the format we used for the
+metadata file is XML. Used namespaces:
+
+- `atom <http://www.w3.org/2005/Atom>`_ (required)
+- `Software Heritage deposit <https://www.softwareheritage.org/schema/2018/deposit>`_
+ (required)
+- `CodeMeta v2 <https://doi.org/10.5063/schema/codemeta-2.0>`_ (recommended)
+- `schema <http://schema.org/>`_ (optional)
+
+.. code-block:: xml
+
+ <?xml version="1.0" encoding="utf-8"?>
+ <entry xmlns="http://www.w3.org/2005/Atom"
+ xmlns:codemeta="https://doi.org/10.5063/schema/codemeta-2.0"
+ xmlns:swh="https://www.softwareheritage.org/schema/2018/deposit">
+ <!-- metadata -->
+ </entry>
+
+SWH deposit's own properties
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This namespace is specific to our implementation of the SWORD v2 protocol, it's used
+to describe what *kind* of deposit the you are doing:
+
+.. tab-set::
+
+ .. tab-item:: Initial deposit
+
+ This is the first time you're making a code deposit for ``ORIGIN_URL``.
+
+ .. code-block:: xml
+
+ <swh:deposit>
+ <swh:create_origin>
+ <swh:origin url="ORIGIN_URL" />
+ </swh:create_origin>
+ </swh:deposit>
+
+ .. tab-item:: New version deposit
+
+ You already made a code deposit for ``ORIGIN_URL`` and you want to send a new
+ version.
+
+ .. code-block:: xml
+
+ <swh:deposit>
+ <swh:add_to_origin>
+ <swh:origin url="ORIGIN_URL" />
+ </swh:add_to_origin>
+ </swh:deposit>
+
+ .. tab-item:: Metadata-only deposit
+
+ You don't have a software artefact to send, only metadata related to a ``SWHID`` or
+ an ``ORIGIN_URL``.
+
+ .. code-block:: xml
+
+ <swh:deposit>
+ <swh:reference>
+ <swh:object swhid="SWHID_CONTEXT" />
+ <!-- or -->
+ <swh:object swhid="SWHID" />
+ <!-- or -->
+ <swh:origin url="ORIGIN_URL" />
+ </swh:reference>
+ </swh:deposit>
+
+CodeMeta
+~~~~~~~~
+
+We're using `CodeMeta <https://codemeta.github.io/>`_ terms to describe the metadata.
+For example:
+
+.. code-block:: xml
+
+ <codemeta:name>A required software name</codemeta:name>
+ <codemeta:url>ORIGIN_URL</codemeta:url>
+ <codemeta:applicationCategory>test</codemeta:applicationCategory>
+ <codemeta:keywords>Some keywords, separated, by, commas</codemeta:keywords>
+ <codemeta:description>An optional description.</codemeta:description>
+ <codemeta:version>1.12</codemeta:version>
+ <codemeta:developmentStatus>stable</codemeta:developmentStatus>
+ <codemeta:programmingLanguage>ocaml</codemeta:programmingLanguage>
+ <codemeta:license>
+ <codemeta:name>GNU Affero General Public License</codemeta:name>
+ </codemeta:license>
+ <codemeta:author>
+ <codemeta:name>Hedy Lamarr</codemeta:name>
+ <codemeta:email>email@example.com</codemeta:email>
+ </codemeta:author>
+
+.. list-table:: Required fields
+ :header-rows: 1
+
+ * - Name
+ - Description
+ * - codemeta:name
+ - The name of this software
+ * - codemeta:author
+ - The author(s) of this software
+
+
+.. list-table:: Recommended fields
+ :header-rows: 1
+
+ * - Name
+ - Description
+ * - codemeta:version
+ - The version of the software, used to differentiate multiple deposits of a same
+ ``ORIGIN_URL``, see versioning below
+ * - codemeta:description
+ - Short or long description of the software
+ * - codemeta:license
+ - The license(s) of the software
+
+See the `full CodeMeta terms list <https://codemeta.github.io/terms/>`_ for a complete
+reference of the available properties.
+
+Versioning
+~~~~~~~~~~
+
+The ``codemeta:version`` property is used to differentiate multiple deposits of a same
+``ORIGIN_URL``. Use cases:
+
+- the software has been updated, you want a make a new deposit of it, you need to
+ increment the ``codemeta:version`` property (if the property is missing we will
+ use a version number reflecting the number of deposits made for this origin)
+- a mistake was made in a previous deposit, you can use make a new one using the same
+ ``codemeta:version`` value. The new snapshot will only contain the latest deposit
+ with this version number
+
+Here is `a snapshot view a an origin`_ listing all distinct versions deposited by HAL
+for the origin ``https://hal.archives-ouvertes.fr/hal-04088473``
+
+.. _a snapshot view a an origin: https://archive.softwareheritage.org/browse/snapshot/f4680770f994ab60a835844168c8b68ee24ac0b8/releases/?origin_url=https://hal.archives-ouvertes.fr/hal-04088473&snapshot=f4680770f994ab60a835844168c8b68ee24ac0b8
+
+Please note that using the same ``codemeta:version`` value for multiple deposits will
+not delete the previous one(s) from the archive: they will still be accessible using
+their SWHID, but they will not appear in the future snapshots.
+
+Metadata provenance
+~~~~~~~~~~~~~~~~~~~
+
+To indicate where the metadata is coming from, deposit clients can use a
+``<swhdeposit:metadata-provenance>`` element in ``<swhdeposit:deposit>`` whose content
+is the object the metadata is coming from.
+
+For example, when the metadata is coming from Wikidata, then the
+provenance should be the page of a
+`Q-entity <https://www.wikidata.org/wiki/Wikidata:Identifiers>`_ or when the
+metadata is coming from a curated repository like HAL, then it should be the HAL
+project.
+
+For example, to deposit metadata on `GNU Hello <https://archive.softwareheritage.org/browse/origin/directory/?origin_url=https://ftp.gnu.org/gnu/hello/>`_:
+
+.. code:: xml
+
+ <swh:deposit>
+ <swh:metadata-provenance>
+ <schema:url>https://www.wikidata.org/wiki/Q16988498</schema:url>
+ </swh:metadata-provenance>
+ </swh:deposit>
+
+Software artefact
+-----------------
+
+Now that your metadata file is ready you'll need to prepare your code artefact by
+packaging the files in a supported archive format:
+
+- ``zip``: common zip archive (no multi-disk zip files).
+- ``tar``: tar archive without compression or compressed using ``gzip``, ``bzip2`` or
+ ``lzma``
+
+Our server will reject files larger than 100MB, so if your artefact is larger than that
+you will have to split it in multiple files and follow the multi-step deposit process.
+
+Tools
+-----
+
+To use the deposit services you will need to make API calls or use our command line
+interface (CLI):
+
+- software used to make API calls: `curl <https://curl.se/>`_,
+ `httpie <https://httpie.io/>`_, etc.
+- `swh-deposit <https://pypi.org/project/swh.deposit/>`_ CLI: ``pip install swh-deposit``
+
+Next step
+---------
+
+You are now ready to make your first deposit!
+
+- You have a single artefact to upload, then follow :doc:`first deposit <first-deposit>`
+- Your artefacts were too large for a simple deposit, then go to
+ :doc:`make a multi-step deposit <multistep-deposit>`
+- You only have metadata to deposit then head to
+ :doc:`metadata-only deposit <metadata-deposit>`
\ No newline at end of file
diff --git a/docs/user/deposit/howto/support.rst b/docs/user/deposit/howto/support.rst
new file mode 100644
index 0000000000000000000000000000000000000000..f0f093d9be6493aa73eb26b7e0110c0953c48e4d
--- /dev/null
+++ b/docs/user/deposit/howto/support.rst
@@ -0,0 +1,55 @@
+Support the deposit service
+===========================
+
+As a non-profit digital commons infrastructure recognized by UNESCO, Software Heritage
+ensures the long-term preservation and universal access of software source code,
+essential for research reproducibility, innovation, and future scholarship.
+
+Support of Software Heritage by organisations is vital in building a mutualized
+infrastructure in service of the society. We are very grateful to all our supporting
+organisations worldwide.
+
+We are actively seeking contributions from institutions, foundations, corporations, and
+individuals that wish to substantially support our mission. Software Heritage will
+officially acknowledge your donation, by various means, according to your sponsorship
+level.
+
+How to support
+--------------
+
+The `Deposit Interest Group`_ (DIG) brings together stakeholders that are interested in
+using, supporting and expanding the Software Heritage infrastructure as the archive of
+choice to deposit open-source software artifacts that they produce or use, with
+appropriate metadata.
+
+The Deposit Interest Group invites you to join the effort through a dedicated program
+and receive acknowledgement in `a dedicated page`_.
+
+Where this support makes a difference
+-------------------------------------
+
+Your support contributes directly to:
+
+1. Infrastructure Development: storage, compute, and network resources to support the
+ ever-growing archive
+2. Innovation and Alignment: stay at the forefront of innovation and aligned with the
+ latest advancements
+3. Long-Term Mission Sustainability: Ensuring operational continuity and financial
+ stability
+4. Community Engagement: foster adoption, grow the community and connecting
+ with partners worldwide
+5. Open Source Preservation: a safe haven for Open Source software, safeguarding it
+ against loss and making it perpetually retrievable
+6. Operational Sustainability: infrastructure expansion, software development, and
+ normal operations to keep the archive and the organization running smoothly
+
+Becoming a DIG member
+---------------------
+
+Members actively enhance the archive by depositing thoroughly reviewed source code via a
+dedicated API with direct support available. Members also participate in the General
+Assembly of the Software Source Code Deposit Interest Group, influencing the technical
+roadmap and community direction.
+
+.. _Deposit Interest Group: https://annex.softwareheritage.org/public/brochures/SWH_DIG_membership_program.pdf
+.. _a dedicated page: https://www.softwareheritage.org/support/sponsors/
\ No newline at end of file
diff --git a/docs/user/deposit/howto/versions.rst b/docs/user/deposit/howto/versions.rst
new file mode 100644
index 0000000000000000000000000000000000000000..3be4c41d8f0ea6cfa0007997d8dd5055bfcc53a5
--- /dev/null
+++ b/docs/user/deposit/howto/versions.rst
@@ -0,0 +1,24 @@
+Deposit a new version of an existing origin
+===========================================
+
+Checklist
+---------
+
+- You have access to your :doc:`account credentials <account>`
+- You have a software artefact at hand and its associated metadata (if not you need to
+ :doc:`prepare your artefacts and metadata <prepare>`.) and you properly
+ used the ``codemeta:version`` property to identify this deposit
+- You already made a deposit for this origin (if not you want to
+ :doc:`make a first code & metadata deposit <first-deposit>`)
+
+
+Send the artefact and the metadata
+----------------------------------
+
+The API calls / CLI commands are the same than the ones described in
+:doc:`make a first code & metadata deposit <first-deposit>` or
+:doc:`make a multi-step deposit <multistep-deposit>`. The only change is the use of
+``swh:add_to_origin`` instead of ``swh:create_origin`` in your metadata file.
+
+Once the status of the deposit is ``done`` you'll be able to check the release tab of
+your archived origin to see the different deposits versions.
\ No newline at end of file
diff --git a/docs/user/deposit/images/Makefile b/docs/user/deposit/images/Makefile
new file mode 100644
index 0000000000000000000000000000000000000000..a029d0c240c9248501edf5014b4501cdfcd6c4dd
--- /dev/null
+++ b/docs/user/deposit/images/Makefile
@@ -0,0 +1,10 @@
+UML_DIAGS_SRC = $(wildcard *.uml)
+UML_DIAGS = $(patsubst %.uml,%.svg,$(UML_DIAGS_SRC))
+
+all: $(UML_DIAGS)
+
+%.svg: %.uml
+ DISPLAY="" plantuml -tsvg $<
+
+clean:
+ -rm -f $(UML_DIAGS)
diff --git a/docs/user/deposit/images/Zenodo_SWH-1536x716.png b/docs/user/deposit/images/Zenodo_SWH-1536x716.png
new file mode 100644
index 0000000000000000000000000000000000000000..2fb7b28ce155075e6c4cf42b52ab427fecba1afb
Binary files /dev/null and b/docs/user/deposit/images/Zenodo_SWH-1536x716.png differ
diff --git a/docs/user/deposit/images/deposit-communication-SWHID-scenario-2.png b/docs/user/deposit/images/deposit-communication-SWHID-scenario-2.png
new file mode 100644
index 0000000000000000000000000000000000000000..263ba3086742ca0e54b86e55ae998597611fa990
Binary files /dev/null and b/docs/user/deposit/images/deposit-communication-SWHID-scenario-2.png differ
diff --git a/docs/user/deposit/index.rst b/docs/user/deposit/index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..5ae43a253a3bf82ff91858fce1deba38538f917b
--- /dev/null
+++ b/docs/user/deposit/index.rst
@@ -0,0 +1,55 @@
+.. _swh-docs-deposit:
+
+Software Heritage Deposit Service
+=================================
+
+.. admonition:: Intended audience
+ :class: important
+
+ Partners working to connect our deposit service to their IT systems.
+
+The deposit service allows a partner to submit software source archives and their
+associated metadata to the |swh| archive.
+
+Metadata can be also submitted referencing a an existing repository url or a
+:ref:`SWHIDs <persistent-identifiers>`.
+
+Explanations
+------------
+
+Read more about the deposit principles and usages.
+
+.. toctree::
+ :maxdepth: 2
+
+ explanations/index
+
+How to guides
+-------------
+
+To assist informed users with their deposits.
+
+.. toctree::
+ :maxdepth: 2
+
+ howto/index
+
+
+References
+----------
+
+Technical documentation and references.
+
+.. toctree::
+ :maxdepth: 2
+
+ references/index
+
+
+.. only:: deposit_doc
+
+ Indices and tables
+ ------------------
+
+ * :ref:`genindex`
+ * :ref:`search`
\ No newline at end of file
diff --git a/docs/user/deposit/references/api.rst b/docs/user/deposit/references/api.rst
new file mode 100644
index 0000000000000000000000000000000000000000..b34bf085f092dcc8386c15dc8c1a060adf7755d7
--- /dev/null
+++ b/docs/user/deposit/references/api.rst
@@ -0,0 +1,13 @@
+API reference
+=============
+
+.. admonition:: Reference implementation
+ :class: note
+
+ We're currently restructuring the documentation. The resource you're looking for is
+ now part of our deposit reference implementation. Clicking the link below will take
+ you to more technical documentation than this. Please come back here afterward to
+ continue.
+
+:ref:`The SWORD v2 API reference for deposit <deposit-api-specifications>` is available
+in ``swh-deposit`` developer's documentation.
diff --git a/docs/user/deposit/references/cli.rst b/docs/user/deposit/references/cli.rst
new file mode 100644
index 0000000000000000000000000000000000000000..92fe389dcf4b9db589b90c2273695ce41c1d37f8
--- /dev/null
+++ b/docs/user/deposit/references/cli.rst
@@ -0,0 +1,13 @@
+Command line interface reference
+================================
+
+.. admonition:: Reference implementation
+ :class: note
+
+ We're currently restructuring the documentation. The resource you're looking for is
+ now part of our deposit reference implementation. Clicking the link below will take
+ you to more technical documentation than this. Please come back here afterward to
+ continue.
+
+:ref:`The CLI reference for deposit <swh-deposit-cli>` is available
+in ``swh-deposit`` developer's documentation.
\ No newline at end of file
diff --git a/docs/user/deposit/references/errors.rst b/docs/user/deposit/references/errors.rst
new file mode 100644
index 0000000000000000000000000000000000000000..50838c548fdfd1afdf26a6af5de7f4fff32225d0
--- /dev/null
+++ b/docs/user/deposit/references/errors.rst
@@ -0,0 +1,58 @@
+Error codes and solutions
+=========================
+
+In case your attempt to deposit an artefact or metadata failed you'll find here
+explanations of the error messages and possible remediation.
+
+.. admonition:: Still stuck?
+ :class: Note
+
+ In case you are not able to troubleshoot the problems you've encountered yourself
+ feel free to reach deposit@softwareheritage.org
+
+401 Unauthorized
+----------------
+
+This status code is returned when something went wrong with the credentials you used
+or the way you used them.
+
+- the API is protected through basic authentication, thus API calls requires username
+ and password sent in the Authorization header
+- make sure the credentials you used match the environment you are targeting (staging
+ or production)
+
+404 Not Found
+-------------
+
+This status code is returned when the resource you're trying to reach is not found.
+
+- double check that the ``DEPOSIT_ID``, ``COLLECTION`` name or path name in the URL are
+ valid
+
+403 Forbidden
+-------------
+
+This status code is returned when the resource you're trying to reach exists and you
+are properly authenticated but not allowed to access it.
+
+- double check that the ``DEPOSIT_ID`` and ``COLLECTION`` name match your deposits
+
+413 Request Entity Too Large
+----------------------------
+
+Your software artefact is too large for the server.
+
+- refer to the :doc:`../howto/prepare` section to find the max size
+ supported by the server
+- split the artefact in multiple parts and follow the :doc:`../howto/multistep-deposit`
+ process
+
+415 Unsupported Media Type
+--------------------------
+
+This status code is returned when a wrong media type is provided when uploading the
+code artefact.
+
+- check the ``type=application/XXX`` header matches your file format
+- refer to the :doc:`../howto/prepare` section to find what kind of file formats are
+ supported
diff --git a/docs/user/deposit/references/index.rst b/docs/user/deposit/references/index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..f705d0749cfe7a21587a57e5995469bfc4ba1efe
--- /dev/null
+++ b/docs/user/deposit/references/index.rst
@@ -0,0 +1,13 @@
+References
+==========
+
+Technical documentation and references.
+
+.. toctree::
+ :maxdepth: 1
+
+ workflow.rst
+ protocol.rst
+ api.rst
+ cli.rst
+ errors.rst
\ No newline at end of file
diff --git a/docs/user/deposit/references/protocol.rst b/docs/user/deposit/references/protocol.rst
new file mode 100644
index 0000000000000000000000000000000000000000..6571f04c2809b1ea6392fce8ee22dadf47251327
--- /dev/null
+++ b/docs/user/deposit/references/protocol.rst
@@ -0,0 +1,13 @@
+Protocol reference
+==================
+
+.. admonition:: Reference implementation
+ :class: note
+
+ We're currently restructuring the documentation. The resource you're looking for is
+ now part of our deposit reference implementation. Clicking the link below will take
+ you to more technical documentation than this. Please come back here afterward to
+ continue.
+
+:ref:`The deposit protocol reference <deposit-protocol>` is available in
+``swh-deposit`` developer's documentation.
\ No newline at end of file
diff --git a/docs/user/deposit/references/workflow.rst b/docs/user/deposit/references/workflow.rst
new file mode 100644
index 0000000000000000000000000000000000000000..a5b40f756f0562c9d110cc78c7388f4dc24fb7fe
--- /dev/null
+++ b/docs/user/deposit/references/workflow.rst
@@ -0,0 +1,13 @@
+Internal Workflows
+==================
+
+.. admonition:: Reference implementation
+ :class: note
+
+ We're currently restructuring the documentation. The resource you're looking for is
+ now part of our deposit reference implementation. Clicking the link below will take
+ you to more technical documentation than this. Please come back here afterward to
+ continue.
+
+:ref:`The workflow reference <swh-deposit-internals>` is available in
+``swh-deposit`` developer's documentation.
\ No newline at end of file
diff --git a/docs/user/index.rst b/docs/user/index.rst
index 2922eec8037007902cf0c92e173a83856646fe38..bb4c7f53e5c64df7c657a8a90cf94b2f7d4c6b16 100644
--- a/docs/user/index.rst
+++ b/docs/user/index.rst
@@ -4,7 +4,7 @@ Usage
=====
.. toctree::
- :maxdepth: 2
+ :maxdepth: 3
faq/index
software-origins/index
@@ -12,6 +12,7 @@ Usage
loaders
save_code_now/webhooks/index
using_data/index
+ deposit/index
.. only:: user_doc
diff --git a/pyproject.toml b/pyproject.toml
index dd9d4e21cdb57cb6e3c2788298ce266fba1b5a09..63eb52eee4b0dfac9f0a5c9c9cafda7638057fa0 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -66,12 +66,11 @@ explicit_package_bases = true
plugins = []
# 3rd party libraries without stubs (yet)
-# [[tool.mypy.overrides]]
-# module = [
-# "package1.*",
-# "package2.*",
-# ]
-# ignore_missing_imports = true
+[[tool.mypy.overrides]]
+module = [
+ "sphinx.*",
+]
+ignore_missing_imports = true
[tool.flake8]
select = ["C", "E", "F", "W", "B950"]