Changeset View
Changeset View
Standalone View
Standalone View
docs/user-manual.rst
Show First 20 Lines • Show All 58 Lines • ▼ Show 20 Lines | |||||
packaging system. For example, on a Debian system: | packaging system. For example, on a Debian system: | ||||
.. _jq: https://stedolan.github.io/jq/ | .. _jq: https://stedolan.github.io/jq/ | ||||
.. code:: console | .. code:: console | ||||
$ sudo apt install jq | $ sudo apt install jq | ||||
.. _prepare_deposit | |||||
Prepare a deposit | Prepare a deposit | ||||
----------------- | ----------------- | ||||
* compress the files in a supported archive format: | * compress the files in a supported archive format: | ||||
- zip: common zip archive (no multi-disk zip files). | - zip: common zip archive (no multi-disk zip files). | ||||
- tar: tar archive without compression or optionally any of the | - tar: tar archive without compression or optionally any of the | ||||
▲ Show 20 Lines • Show All 70 Lines • ▼ Show 20 Lines | * a single deposit (archive + metadata): | ||||
The deposit is directly marked with status ``deposited``. | The deposit is directly marked with status ``deposited``. | ||||
* a multisteps deposit: | * a multisteps deposit: | ||||
1. Create an incomplete deposit (marked with status ``partial``) | 1. Create an incomplete deposit (marked with status ``partial``) | ||||
2. Add data to a deposit (in multiple requests if needed) | 2. Add data to a deposit (in multiple requests if needed) | ||||
3. Finalize deposit (the status becomes ``deposited``) | 3. Finalize deposit (the status becomes ``deposited``) | ||||
* a metadata-only deposit: | |||||
The user posts in one query an associated metadata file on a :ref:`SWHID | |||||
<persistent-identifiers>` object. The deposit is directly marked with status | |||||
``done``. | |||||
Overall, a deposit can be a in series of steps as follow: | Overall, a deposit can be a in series of steps as follow: | ||||
.. figure:: images/status.svg | .. figure:: images/status.svg | ||||
:alt: | :alt: | ||||
The important things to notice for now is that it can be: | The important things to notice for now is that it can be: | ||||
▲ Show 20 Lines • Show All 108 Lines • ▼ Show 20 Lines | (deposit)$ swh deposit status --username <name> --password <secret> \ | ||||
"deposit_status": "done", | "deposit_status": "done", | ||||
"deposit_status_detail": "The deposit has been successfully loaded into the Software Heritage archive", | "deposit_status_detail": "The deposit has been successfully loaded into the Software Heritage archive", | ||||
"deposit_swh_id": "swh:1:dir:63a6fc0ed8f69bf66ccbf99fc0472e30ef0a895a", | "deposit_swh_id": "swh:1:dir:63a6fc0ed8f69bf66ccbf99fc0472e30ef0a895a", | ||||
"deposit_swh_id_context": "swh:1:dir:63a6fc0ed8f69bf66ccbf99fc0472e30ef0a895a;origin=https://softwareheritage.org/belenios-01234065;visit=swh:1:snp:0ae536667689da7047bfb7aa9f37f5958e9f4647;anchor=swh:1:rev:17ad98c940104d45b6b6bd6fba9aa832eeb95638;path=/", | "deposit_swh_id_context": "swh:1:dir:63a6fc0ed8f69bf66ccbf99fc0472e30ef0a895a;origin=https://softwareheritage.org/belenios-01234065;visit=swh:1:snp:0ae536667689da7047bfb7aa9f37f5958e9f4647;anchor=swh:1:rev:17ad98c940104d45b6b6bd6fba9aa832eeb95638;path=/", | ||||
"deposit_external_id": "belenios-01234065" | "deposit_external_id": "belenios-01234065" | ||||
} | } | ||||
Metadata-only deposit | |||||
^^^^^^^^^^^^^^^^^^^^^ | |||||
This allows to deposit only metadata information on a :ref:`SWHID reference | |||||
<persistent-identifiers>`. Prepare a metadata file as described in the | |||||
:ref:`prepare deposit section <prepare-deposit>` | |||||
Ensure this metadata file also declares a :ref:`SWHID reference | |||||
<persistent-identifiers>`: | |||||
.. code:: xml | |||||
<entry ... | |||||
xmlns:swh="https://www.softwareheritage.org/schema/2018/deposit" | |||||
> | |||||
<!-- ... --> | |||||
<swh:deposit> | |||||
<swh:reference> | |||||
<swh:object swhid="swh:1:dir:31b5c8cc985d190b5a7ef4878128ebfdc2358f49" /> | |||||
</swh:reference> | |||||
</swh:deposit> | |||||
<!-- ... --> | |||||
</entry> | |||||
For this, we then need to provide the following information: | |||||
* arguments: ``--username 'name' --password 'pass'`` as credentials | |||||
* metadata file path (example: ``--metadata path/to/metadata.xml``) | |||||
to the `swh deposit metadata-only` command. | |||||
Example: | |||||
.. code:: console | |||||
(deposit) swh deposit metadata-only --username <name> --password <secret> \ | |||||
--url https://deposit.staging.swh.network/1 \ | |||||
--metadata ../deposit-swh.metadata-only.xml \ | |||||
--format json | jq . | |||||
{ | |||||
"deposit_id": "29", | |||||
"deposit_status": "done", | |||||
"deposit_date": "Dec. 15, 2020, 11:37 a.m." | |||||
} | |||||
For details on the metadata-only deposit, see the | |||||
:ref:`metadata-only deposit protocol reference <metadata-only-deposit>` | |||||
Multisteps deposit | Multisteps deposit | ||||
^^^^^^^^^^^^^^^^^^ | ^^^^^^^^^^^^^^^^^^ | ||||
In this case, the deposit is created by several requests, uploading objects | In this case, the deposit is created by several requests, uploading objects | ||||
piece by piece. The steps to create a multisteps deposit: | piece by piece. The steps to create a multisteps deposit: | ||||
1. Create an partial deposit | 1. Create an partial deposit | ||||
▲ Show 20 Lines • Show All 130 Lines • Show Last 20 Lines |