First Comments on spec

[MarkusKonk]

1. "These typically consist of data, code and libraries in executable form which are needed to re-do an analysis, and the outputs of the original analysis." - not an easy sentence
2. required fields for erc.yml do not match minimal example
3. "Default command statements of implementing tools" - "for" instead of "of"?
4. is time zone a MUST?
5. link to o2r-metadata schema?
6. Example configuration file at the end? Or a link?
7. Example docker file?
8. Is it possible that I can avoid the entire validation process by using the .ercignore file? Should that be possible?
9. Validation of research results is missing in Validation, right?

I am not sure if I understood each point in sufficient detail. I will re-read it on a later occasion.

[nuest]

Re 1: rephrased Re 2: allways using spec_version Re 3: sentence already updated Re 4: no, the previous sentence, to which the time zone is an example, say "SHOULD ensure..." Re 5: the schema should become part of the spec imho. @7048730 what do you think? should we publish the metadata schema independently and just reference it from the spec? Re 6: the last section is a "comprehensive example". do you suggest to put in a file here instead of an embedded example? Re 7: added example Re 8: yes, that is possible... added should statements on communicating the (not) used files to the user. Re 9: The ERC cannot validate results, only computations. If there are output files that can be compared and they are not .ercignored, then the validation works on "results".

[ghost]

The schema documentation should be moved here. Working on an update anyway. Will suggest via PR here when ready. The o2r schema json itself should be linked (or mirrored) as it will be curated primarily as part of the meta suite.

[MarkusKonk]

@nuest Second review:

1. ... as a research object...?
2. cf. computational science) bracket missing on a researcher's computer
3. "The research is put into context in a text/publication that is part scholarly communication." (rephrase?)
4. ...allows understanding, reproducing... and reusing?
5. "...collection of files which make up an ERC comprise one or more containers but are themselves subject to being put into a container." (I didn't get this one)
6. "compare the output contained in the bag with the just created new output" - to me "output" reads like "results" which you negated in Re 9. What exactly is "output" then?
7. "The main documents name SHOULD be paper with an appropriate extension, e.g. .tex". - Rmd instead of tex because we don't consider tex at the moment.
8. mention that display file is usually the rendered version of the main file?
9. "This section defines two such representations, one documenting and one executable." - rephrase?
10. "SHOULD be stated more precisely in an extension." - of this specification? While reading the spec, I sometimes got confused because of the many extensions.
11. "...or to rely on constructing it from the runtime manifest (see below)." - otherwise manifest appears all of a sudden
12. "The output of the image execution can be shown to the user to convey..." - user = reader + author alike?
13. "The base directory SHOULD contain a runnable image" - Link to how to create an image?
14. "This manifest MUST be in a machine-readable format that allows a respective tool to create the runtime image." - explain why you need to create a runtime image which should be included anyway How about specifying which machine-readable format you expect? Example of a manifest?
15. "A concrete runtime extension..." - do you refer to docker runtime extension? Link?
16. Bundline = Bundling?
17. Is "Runtime manipulation" related to my part which are UI bindings? In that case I don't understand why parameters need to be defined in a concrete runtime extension
18. where do I get the URI for the configuration file from?
19. "Schould"
20. "This list can have different formats for different use cases or depending on the source of information" - it sounds very generic. Can we handle everything?
21. I am not sure about the implications of the .ercignore file and from which processes they are excluded at the end. Users might think that these files are not visible or submitted. Is this the case?
22. What exactly is meant by comparing results during ERC validation? What are the results of the runtime container execution? - checksums?
23. Domain or use case specific metadata SHOULD replicate all and only the information required for the specific case. - "use case-specific", don't understand the sentence
24. Include license example in yml example at the end?

[nuest]

Re 1.: I don't know what you refer to, I do not find that text in the spec. Re 2.: Fixed. Re 3.: I tried, but feel free to suggest something. Re 4.: Changed. Re 5.: Rephrased. Re 6.: Rephrased. Re 7.: Just an example, but changed anyway. I also changed the suggested names for the documents to main and view. Re 8.: Added. Re 9.: Rephrased. Re 10.: Clarified. Re 11.: Rephrased. Re 12.: Yes. Do you see a need to distinguish here between reader and author? Re 13.: No, we do not specific that here. Re 14.: See explanations in developer guide. Re 15.: No, we do not mention Docker is the base spec. Re 16.: Fixed. Re 17.: Yes, that is related to UI bindings. Without knowing the actual way an image is executed (or if there even is an image), we cannot specific how parameters can be passed to it. Re 18.: I assume you mean the URI for the id within the configuration file? We don't care. Get it wherever you can. Re 19.: Fixed. Re 20.: It is generic. We cannot handle anything as we do not use any of these files, but they should be there to support reproducibility. Rephrased section. Re 21.: As of now they are only excluded from validation, so I changed the sentence. Since the section does say anything about (in)visible files or submitting files, I do not see any reason for confusion. Re 22.: Rephrased. Re 23.: Rephrased whole section, hope it's clearer now. Re 24.: extended final example.