Last modified by adavison on 2024/11/13 10:32
From version 41.1
edited by adavison
on 2024/11/08 17:15
Change comment: Renamed back-links.
To version 42.2
edited by adavison
on 2024/11/13 10:22
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -1,85 +1,21 @@
1 -= Contents[[~[~[image:EBRAINS-Share-Software.jpg~|~|alt="Infographic Software Curation" height="532" style="float:right" width="298"~]~]>>https://drive.ebrains.eu/lib/f5cf4964-f095-49bd-8c34-e4ffda05a497/file/EBRAINS-Share-Software.pdf]] =
1 +== Audience ==
2 2  
3 -{{toc start="2"/}}
3 +This guide is for software developers who would like to register their software in the EBRAINS Knowledge Graph.
4 4  
5 -This guide provides a starting point and reference for the process of entering information about your software
6 -into the EBRAINS Knowledge Graph (KG).
5 +== Introduction ==
7 7  
8 -For an overview of the software curation process, please refer to [[our info graphic>>https://drive.ebrains.eu/lib/f5cf4964-f095-49bd-8c34-e4ffda05a497/file/EBRAINS-Share-Software.pdf]].
7 +Most software changes over time, with new features or bug fixes, and new releases. For scientific research to be reproducible, it is important to keep track of which versions of software were used for a given study. This means it needs to be easy for the developers of software used in the EBRAINS Research Infrastructure to keep the information about their software up-to-date, and to register new versions of their software when they are released.
9 9  
10 -**For any questions or support directly reach out to [[Jan Gründling>>mailto:gruendling@uni-trier.de]].**
9 +For this reason, the process of adding information about software and software versions has been automated as much as possible. Two methods are available:
11 11  
11 +1. providing a codemeta.json file in your software repository.
12 +1. publishing software through Zenodo.
12 12  
14 +== Method 1: Providing a codemeta.json file in your software repository ==
13 13  
16 +[[CodeMeta>>https://codemeta.github.io/||rel=" noopener noreferrer" target="_blank"]] is a project developed by a number of actors involved in sharing software, including Zenodo, GitHub, DataCite and Software Heritage, to provide a common specification for software metadata. EBRAINS has adopted the CodeMeta specification to maximise interoperability with other software repositories, and to minimise the added burden on software developers. A web form for generating codemeta.json files is available at [[https:~~/~~/codemeta.github.io/codemeta-generator/>>https://codemeta.github.io/codemeta-generator/||rel=" noopener noreferrer" target="_blank"]], provided by Software Heritage.
14 14  
15 15  
19 +== Method 2: Publishing software through Zenodo ==
16 16  
17 -
18 -
19 -----
20 -
21 -== How to enter software metadata manually ==
22 -
23 -If your software has not been curated before, please fill in the request form [[here>>https://nettskjema.no/a/277393]] before continuing with the following instructions. If your Software has been curated already and you want do add a new version, refer to the section [[How to Update>>https://wiki.ebrains.eu/bin/view/Collabs/swc-guide#HHowtoupdateexistingSoftwareinstances]].
24 -
25 -You will receive an email after the curator has created a space for you in the Knowledge Graph. This email contains a link to a software instance and a software version instance in your Space. These are already linked to each other (by the attribute "Has Version" of the software instance).
26 -
27 -**Before explaining the editing process, here are some helpful links:**
28 -
29 -* A description of the fields of the software and software version instances and values that these fields may take: [[https:~~/~~/humanbrainproject.github.io/openMINDS/v2/core/v3/products/softwareVersion.html>>url:https://humanbrainproject.github.io/openMINDS/v2/core/v3/products/softwareVersion.html]] and [[https:~~/~~/humanbrainproject.github.io/openMINDS/v2/core/v3/products/software.html>>url:https://humanbrainproject.github.io/openMINDS/v2/core/v3/products/software.html]]
30 -* Additional information for each attribute: [[Attribute Description>>doc:Collabs.swc-guide.Archive.Attribute description.WebHome]]
31 -* A detailed description of the software features: [[Software Features>>doc:Collabs.swc-guide.Archive.Software Features.WebHome]]
32 -
33 -**Editing the software and software version instances:**
34 -
35 -To register your software, you will need to input information for the instance "Software" and for  "Software version". After clicking the links in your email, you will see an instance editor view like below:
36 -
37 -[[image:Collabs.swc-guide.Archive.EBRAINS Knowledge Graph guide for software curation.WebHome@guide1.JPG]]
38 -
39 -As you can see in the screenshot above, some fields are marked with an asterisk (*). These are required. Keep in mind that this is how you present your software publicly to potential end-users or other researchers. Therefore it would be nice if as many fields as possible are filled in.
40 -
41 -Some fields can be of different types, such as the field "Developer" and "Full documentation". In the case of developer it is possible to enter a person or an organisation. The possible types are selectable on the right above the respective field, as shown in the following screenshots:
42 -
43 -[[image:Collabs.swc-guide.Archive.EBRAINS Knowledge Graph guide for software curation.WebHome@guideDev.JPG||height="109" width="600"]]
44 -
45 -[[image:Collabs.swc-guide.Archive.EBRAINS Knowledge Graph guide for software curation.WebHome@guide21.JPG||height="142" width="600"]]
46 -
47 -For example, if you want to create a new person, an editing field opens in the right column of the instance editor view as shown in the following screenshot.
48 -
49 -[[image:Collabs.swc-guide.Archive.EBRAINS Knowledge Graph guide for software curation.WebHome@guide6.JPG]]
50 -
51 -If you are not sure which type to use, please refer to the descriptions linked above or contact the curator.
52 -
53 -After you have entered your information on the software, **do not forget to save your changes **(see screenshot below) and contact the curator.
54 -
55 -[[image:Collabs.swc-guide.Archive.EBRAINS Knowledge Graph guide for software curation.WebHome@guide4.JPG||height="189" width="400"]]
56 -
57 -The curators will check the new software instances and move them to the correct space.
58 -
59 -
60 -(% class="box infomessage" %)
61 -(((
62 -[[image:lamp-gcbdd1eea5_640-2.png||height="50" style="float:left" width="50"]]The term "instance" in context of the Knowledge Graph Editor refers to the one specific software or software version respectively.
63 -)))
64 -
65 -== How to update existing Software instances ==
66 -
67 -If you have registered a software previously, updating means adding a new instance of type "Software version". Curators will later link it to the existing instance of type "Software".
68 -
69 -**If you want to add a new version to an already curated software, please write to [[curation-support@humanbrainproject.eu>>path:mailto:curation-support@humanbrainproject.eu]] or open a ticket [[here>>https://ebrains.eu/support/]]**
70 -
71 -To make updating easier, we place a copy of your last software version instance in the KG space that was created for you. You can use that copy and just change the fields that require changes. As you are editing copies of published information, you will not change the already curated information, but rather use it as a starting point for the data that you add. Again - if you made all changes that you consider necessary, let the curator know via email or the ticket assigned with this case.
72 -
73 -If you want to add more versions, you can always use the "Duplicate this instance" button found in the management tab by clicking the cogwheel on the left side:
74 -
75 -[[image:image-20230207135131-1.png]]
76 -
77 -== How to upload software metadata programmatically ==
78 -
79 -To create a valid jsonld file, please use the [[API>>https://core.kg.ebrains.eu/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config]].
80 -
81 -==== Authorizing for API usage. ====
82 -
83 -Before using it, you need to authorize, using the "Authorize" button found in the top right corner of the API documentation (see below) or by using a service account.
84 -
85 -[[image:Collabs.swc-guide.Archive.EBRAINS Knowledge Graph guide for software curation.WebHome@image-20220323111341-2.png||height="74" width="186"]]
21 +More information coming soon.