Differential D1429 Diff 4704 docs/getting-started.rst

Changeset 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
		ardumontUnsubmitted Not Done Inline Actions missing the \ and indentation is off. 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