Page MenuHomeSoftware Heritage

doc: add an introduction paragraph in blueprint.rst
ClosedPublic

Authored by douardda on Nov 6 2020, 10:59 AM.

Details

Summary

and move the list of deposit statuses there instead of repeating it 3
times.

Also reference the API endpoints used in the deposit creation scenario.

Depends on D4428.

Diff Detail

Event Timeline

Build is green

Patch application report for D4429 (id=15685)

Could not rebase; Attempt merge onto 0f4ec31168...

Updating 0f4ec311..912be1d0
Fast-forward
 docs/endpoints/collection.rst       | 116 ++++++++++++----------
 docs/endpoints/content.rst          |  65 +++++++++++-
 docs/endpoints/service-document.rst |  80 +++++++++------
 docs/endpoints/status.rst           |  63 ++++++------
 docs/endpoints/update-media.rst     |  16 +--
 docs/endpoints/update-metadata.rst  |  10 +-
 docs/index.rst                      |   2 +-
 docs/spec-api.rst                   |  29 +++---
 docs/specs/blueprint.rst            | 192 +++++++++++++++++-------------------
 docs/specs/{specs.rst => index.rst} |   0
 docs/specs/spec-loading.rst         | 119 +++++++++++-----------
 11 files changed, 386 insertions(+), 306 deletions(-)
 rename docs/specs/{specs.rst => index.rst} (100%)
Changes applied before test
commit 912be1d02839250950b2770c79d332ccf0ccd0ef
Author: David Douard <david.douard@sdfa3.org>
Date:   Fri Nov 6 09:39:24 2020 +0100

    doc: add an introduction paragraph in blueprint.rst
    
    and move the list of deposit statuses there instead of repeating it 3
    times.
    
    Also reference the API endpoints used in the deposit creation scenario.

commit 489f1ab76caa54b50e7523c058b4d5034e66d858
Author: David Douard <david.douard@sdfa3.org>
Date:   Fri Nov 6 09:36:29 2020 +0100

    doc: improve the spec-loading doc
    
    - update some deprecated statements (tar loader -> deposit loader)
    - explcit API calls for example JSON snippets
    - update JSON snippets for current API behavior

commit 61653ddfc7c38bd4130374a6b6472f55f358138a
Author: David Douard <david.douard@sdfa3.org>
Date:   Thu Nov 5 16:16:07 2020 +0100

    doc: improve the doc of API endpoints
    
    make usage of the sphinx-httpdomain extension according to its
    documenation.

commit 1736371f2c6da9713e4f815da99cd3cd624fdaad
Author: David Douard <david.douard@sdfa3.org>
Date:   Thu Nov 5 14:21:40 2020 +0100

    doc: rename docs/specs/specs.rst as docs/specs/index.rst
    
    for the sake of clarity.

See https://jenkins.softwareheritage.org/job/DDEP/job/tests-on-diff/283/ for more details.

Thank you for doing this important review of the deposit documentation.
I started commenting, and get back to this later.

docs/specs/blueprint.rst
24

just partially received. if the deposit is done in one go it won't start as partial, it will be directly deposited.

32

new deposit received (before checks)

thanks! just a few nitpicks:

docs/specs/blueprint.rst
8

s/Each/A/

13

s/validation checks then/validation checks. Then/

23–47

what is this :xxx: syntax? It looks like it's the "field list" https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#field-lists , and this isn't what we want here.

The original used the "definition list" syntax: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#definition-lists

81

s/PUT or POST/POST (or PUT)/

POST is semantically the right verb for this, we just happen to also support PUT.

douardda added inline comments.
docs/specs/blueprint.rst
23–47

I changed mainly for visual aspect reason I guess, can go back to semantically correct constuction :-)

81

no these are not the same, one is an amend, to other is a replace (IIRC)

docs/specs/blueprint.rst
23–47

definition list:

field list:

docs/specs/blueprint.rst
81

oh, I didn't realize SWORD allowed both. Alright then

Build is green

Patch application report for D4429 (id=15698)

Rebasing onto 04c1114508...

Current branch diff-target is up to date.
Changes applied before test
commit 2daa09ed7b09b209d0ce2dac6ad138fa7c81ae61
Author: David Douard <david.douard@sdfa3.org>
Date:   Fri Nov 6 09:39:24 2020 +0100

    doc: add an introduction paragraph in blueprint.rst
    
    and move the list of deposit statuses there instead of repeating it 3
    times.
    
    Also reference the API endpoints used in the deposit creation scenario.

See https://jenkins.softwareheritage.org/job/DDEP/job/tests-on-diff/289/ for more details.

good catch with the v2 precision.
I also agree that the statuses should be higher in the document.
I don't know if the status diagram is in here or somewhere else, it might be relevant to show it or put a link in.

ardumont added a subscriber: ardumont.

nice, thanks.

docs/specs/blueprint.rst
28

as a side note to share the info, nothing is doing that at the moment.

This revision is now accepted and ready to land.Nov 6 2020, 1:37 PM
docs/specs/blueprint.rst
28

yes but the world does not need to know :-)

docs/specs/blueprint.rst
28

(yes, i meant to share the info here with you, not within the doc ;)

This revision was landed with ongoing or failed builds.Nov 9 2020, 9:38 AM
This revision was automatically updated to reflect the committed changes.

Build is green

Patch application report for D4429 (id=15723)

Rebasing onto a67a8cc770...

Current branch diff-target is up to date.
Changes applied before test
commit 7148a257b296047d8e03d43fe1739404820ca9bb
Author: David Douard <david.douard@sdfa3.org>
Date:   Fri Nov 6 09:39:24 2020 +0100

    doc: add an introduction paragraph in blueprint.rst
    
    and move the list of deposit statuses there instead of repeating it 3
    times.
    
    Also reference the API endpoints used in the deposit creation scenario.

See https://jenkins.softwareheritage.org/job/DDEP/job/tests-on-diff/293/ for more details.