Changeset View
Changeset View
Standalone View
Standalone View
docs/getting-started.rst
Getting Started | Getting Started | ||||
=============== | =============== | ||||
This is a guide for how to prepare and push a software deposit with | This is a guide for how to prepare and push a software deposit with | ||||
the swh-deposit commands. | the `swh deposit` commands. | ||||
The api is rooted at https://deposit.softwareheritage.org/1. | The API is rooted at https://deposit.softwareheritage.org/1. | ||||
For more details, see the `main documentation <./index.html>`__. | For more details, see the `main documentation <./index.html>`__. | ||||
Requirements | Requirements | ||||
------------ | ------------ | ||||
You need to be referenced on SWH's client list to have: | You need to be referenced on SWH's client list to have: | ||||
* credentials (needed for the basic authentication step) | * credentials (needed for the basic authentication step) | ||||
- in this document we reference ``<name>`` as the client's name and | - in this document we reference ``<name>`` as the client's name and | ||||
``<pass>`` as its associated authentication password. | ``<pass>`` as its associated authentication password. | ||||
* an associated collection | * an associated collection_. | ||||
`Contact us for more | .. _collection: https://bitworking.org/projects/atom/rfc5023#rfc.section.8.3.3 | ||||
information. <https://www.softwareheritage.org/contact/>`__ | |||||
`Contact us for more information. | |||||
<https://www.softwareheritage.org/contact/>`__ | |||||
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 | ||||
following compression algorithm gzip (.tar.gz, .tgz), bzip2 | following compression algorithm gzip (`.tar.gz`, `.tgz`), bzip2 | ||||
(.tar.bz2) , or lzma (.tar.lzma) | (`.tar.bz2`) , or lzma (`.tar.lzma`) | ||||
* prepare a metadata file (`more details <./metadata.html>`__.): | * prepare a metadata file (`more details <./metadata.html>`__.): | ||||
- specify metadata schema/vocabulary (CodeMeta is recommended) | - specify metadata schema/vocabulary (CodeMeta is strongly recommended) | ||||
- specify *MUST* metadata (url, authors, software name and | - specify *MUST* metadata (url, authors, software name and | ||||
the external\_identifier) | the external\_identifier) | ||||
- add all available information under the compatible metadata term | - add all available information under the compatible metadata term. | ||||
An example of an atom entry file with CodeMeta terms: | Here is an example of an atom entry file with CodeMeta terms: | ||||
.. code:: xml | .. code:: xml | ||||
<?xml version="1.0" encoding="utf-8"?> | <?xml version="1.0" encoding="utf-8"?> | ||||
<entry xmlns="http://www.w3.org/2005/Atom" | <entry xmlns="http://www.w3.org/2005/Atom" | ||||
xmlns:codemeta="https://doi.org/10.5063/SCHEMA/CODEMETA-2.0"> | xmlns:codemeta="https://doi.org/10.5063/SCHEMA/CODEMETA-2.0"> | ||||
<title>Je suis GPL</title> | <title>Je suis GPL</title> | ||||
<client>swh</client> | <client>swh</client> | ||||
▲ Show 20 Lines • Show All 59 Lines • ▼ Show 20 Lines | * (optionally) ``--slug 'your-id'`` argument, a reference to a | ||||
unique identifier the client uses for the software object. | unique identifier the client uses for the software object. | ||||
You can do this with the following command: | You can do this with the following command: | ||||
minimal deposit | minimal deposit | ||||
.. code:: shell | .. code:: shell | ||||
$ swh-deposit deposit --username name --password secret \ | $ swh deposit upload --username name --password secret \ | ||||
--archive je-suis-gpl.tgz | --archive je-suis-gpl.tgz | ||||
with client's external identifier (``slug``) | with client's external identifier (``slug``) | ||||
.. code:: shell | .. code:: shell | ||||
$ swh-deposit deposit --username name --password secret \ | $ swh deposit upload --username name --password secret \ | ||||
--archive je-suis-gpl.tgz \ | --archive je-suis-gpl.tgz \ | ||||
--slug je-suis-gpl | --slug je-suis-gpl | ||||
to a specific client's collection | to a specific client's collection | ||||
.. code:: shell | .. code:: shell | ||||
$ swh-deposit deposit --username name --password secret \ | $ swh deposit upload --username name --password secret \ | ||||
--archive je-suis-gpl.tgz \ | --archive je-suis-gpl.tgz \ | ||||
--collection 'second-collection' | --collection 'second-collection' | ||||
You just posted a deposit to your collection on Software Heritage | You just posted a deposit to your collection on Software Heritage | ||||
If everything went well, the successful response will contain the | If everything went well, the successful response will contain the | ||||
elements below: | elements below: | ||||
Show All 31 Lines | |||||
The steps to create a multisteps deposit: | The steps to create a multisteps deposit: | ||||
1. Create an incomplete deposit | 1. Create an incomplete deposit | ||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||||
First use the ``--partial`` argument to declare there is more to come | First use the ``--partial`` argument to declare there is more to come | ||||
.. code:: shell | .. code:: shell | ||||
$ swh-deposit deposit --username name --password secret \ | $ swh deposit upload --username name --password secret \ | ||||
--archive foo.tar.gz \ | --archive foo.tar.gz \ | ||||
--partial | --partial | ||||
2. Add content or metadata to the deposit | 2. Add content or metadata to the deposit | ||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||||
Continue the deposit by using the ``--deposit-id`` argument given as a response | Continue the deposit by using the ``--deposit-id`` argument given as a response | ||||
for the first step. You can continue adding content or metadata while you use | for the first step. You can continue adding content or metadata while you use | ||||
the ``--partial`` argument. | the ``--partial`` argument. | ||||
.. code:: shell | .. code:: shell | ||||
$ swh-deposit deposit --username name --password secret \ | $ swh deposit upload --username name --password secret \ | ||||
--archive add-foo.tar.gz \ | --archive add-foo.tar.gz \ | ||||
--deposit-id 42 \ | --deposit-id 42 \ | ||||
--partial | --partial | ||||
In case you want to add only one new archive without metadata: | In case you want to add only one new archive without metadata: | ||||
.. code:: shell | .. code:: shell | ||||
$ swh-deposit deposit --username name --password secret \ | $ swh deposit upload --username name --password secret \ | ||||
--archive add-foo.tar.gz \ | --archive add-foo.tar.gz \ | ||||
--archive-deposit \ | --archive-deposit \ | ||||
--deposit-id 42 \ | --deposit-id 42 \ | ||||
--partial \ | --partial | ||||
If you want to add only metadata, use: | If you want to add only metadata, use: | ||||
.. code:: shell | .. code:: shell | ||||
$ swh-deposit deposit --username name --password secret \ | $ swh deposit upload --username name --password secret \ | ||||
--metadata add-foo.tar.gz.metadata.xml \ | --metadata add-foo.tar.gz.metadata.xml \ | ||||
--metadata-deposit \ | --metadata-deposit \ | ||||
--deposit-id 42 \ | --deposit-id 42 \ | ||||
--partial | --partial | ||||
3. Finalize deposit | 3. Finalize deposit | ||||
~~~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~~~~~~~ | ||||
On your last addition, by not declaring it as ``--partial``, the | On your last addition, by not declaring it as ``--partial``, the | ||||
deposit will be considered as completed and its status will be changed | deposit will be considered as completed and its status will be changed | ||||
to ``deposited``. | to ``deposited``: | ||||
.. code:: shell | |||||
$ swh deposit upload --username name --password secret \ | |||||
--metadata add-foo.tar.gz.metadata.xml \ | |||||
--metadata-deposit \ | |||||
--deposit-id 42 | |||||
Update deposit | Update deposit | ||||
---------------- | ---------------- | ||||
* replace deposit: | * replace deposit: | ||||
- only possible if the deposit status is ``partial`` and | - only possible if the deposit status is ``partial`` and | ||||
``--deposit-id <id>`` is provided | ``--deposit-id <id>`` is provided | ||||
- by using the ``--replace`` flag | - by using the ``--replace`` flag | ||||
- ``--metadata-deposit`` replaces associated existing metadata | - ``--metadata-deposit`` replaces associated existing metadata | ||||
- ``--archive-deposit`` replaces associated archive(s) | - ``--archive-deposit`` replaces associated archive(s) | ||||
- by default, with no flag or both, you'll replace associated | - by default, with no flag or both, you'll replace associated | ||||
metadata and archive(s) | metadata and archive(s): | ||||
.. code:: shell | .. code:: shell | ||||
$ swh-deposit deposit --username name --password secret \ | $ swh deposit upload --username name --password secret \ | ||||
--deposit-id 11 \ | --deposit-id 11 \ | ||||
--archive updated-je-suis-gpl.tgz \ | --archive updated-je-suis-gpl.tgz \ | ||||
--replace | --replace | ||||
* update a loaded deposit with a new version: | * update a loaded deposit with a new version: | ||||
- by using the external-id with the ``--slug`` argument, you will | - by using the external-id with the ``--slug`` argument, you will | ||||
link the new deposit with its parent deposit | link the new deposit with its parent deposit: | ||||
.. code:: shell | .. code:: shell | ||||
$ swh-deposit deposit --username name --password secret \ | $ swh deposit upload --username name --password secret \ | ||||
--archive je-suis-gpl-v2.tgz \ | --archive je-suis-gpl-v2.tgz \ | ||||
--slug 'je-suis-gpl' \ | --slug 'je-suis-gpl' \ | ||||
Check the deposit's status | Check the deposit's status | ||||
-------------------------- | -------------------------- | ||||
You can check the status of the deposit by using the ``--deposit-id`` argument: | You can check the status of the deposit by using the ``--deposit-id`` argument: | ||||
.. code:: shell | .. code:: shell | ||||
$ swh-deposit deposit --username name --password secret --deposit-id '11' --status | $ swh deposit upload --username name --password secret \ | ||||
--deposit-id 11 \ | |||||
ardumont: missing the \ and indentation is off. | |||||
--status | |||||
.. code:: json | .. code:: json | ||||
{ | { | ||||
'deposit_id': '11', | 'deposit_id': '11', | ||||
'deposit_status': 'deposited', | 'deposit_status': 'deposited', | ||||
'deposit_swh_id': None, | 'deposit_swh_id': None, | ||||
'deposit_status_detail': 'Deposit is ready for additional checks \ | 'deposit_status_detail': 'Deposit is ready for additional checks \ | ||||
Show All 30 Lines |
missing the \ and indentation is off.