README.md 6.01 KB
Newer Older
vuillaut's avatar
vuillaut committed
1
# ESCAPE metadata template
Vuillaume's avatar
Vuillaume committed
2

Enrique Garcia's avatar
Enrique Garcia committed
3 4 5
Among the [OSSR guidelines and rules of participation](
https://escape2020.pages.in2p3.fr/wp3/ossr-pages/page/contribute/contribute_ossr/) - agreed between the ESCAPE WP3 participants -, 
we **strongly recommend** to include a metadata descriptive file into the entry to be uploaded to the ESCAPE repository.
vuillaut's avatar
vuillaut committed
6

Enrique Garcia's avatar
Enrique Garcia committed
7 8 9 10
In the ESCAPE context, the use of the [CodeMeta schema](https://codemeta.github.io/) is strongly advised for uploads containing software. 
However, we support and encourage the use of any other metadata standard. If this is the case, please contact us 
(see just below). However, please note that the GitLab-Zenodo connection only supports - at the moment - codemeta metadata
 descriptive files.  
vuillaut's avatar
vuillaut committed
11

Enrique Garcia's avatar
Enrique Garcia committed
12
Any comments are more than welcome. Open an issue or contact us [via email](mailto:vuillaume@lapp.in2p3.fr;garcia@lapp.in2p3.fr).
vuillaut's avatar
vuillaut committed
13

Enrique Garcia's avatar
Enrique Garcia committed
14
## Quickstart - How to incorporate a CodeMeta metadata file into your project.
Enrique Garcia's avatar
Enrique Garcia committed
15

Enrique Garcia's avatar
Enrique Garcia committed
16
 1. Go to the [CodeMeta generator](https://codemeta.github.io/codemeta-generator/). Generate a `codemeta.json` file based on your project.
Enrique Garcia's avatar
Enrique Garcia committed
17
    - Check - in the same web application - that the generated file is valid !  
Enrique Garcia's avatar
Enrique Garcia committed
18 19 20
 2. Copy the generated metadata into a `codemeta.json` file and include it in the **root directory** of your project.
 3. Please **pay attention to the `keywords` field**. Include **at least one** of the following keywords **per category**; 
 besides all the keywords that you would like to attach to your project.   
Enrique Garcia's avatar
Enrique Garcia committed
21

Enrique Garcia's avatar
Enrique Garcia committed
22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59
### Keywords list

In your `codemeta.json` file **add, at least,** one keywords of the following **three** categories:

Multiple keywords must be separated with a comma `,` and between double `"`;
```json
 {
   ...
 "keywords": ["CTA", "Astroparticle physics", "jupyter-notebook", ...],
   ...  
}
```

1. Project category:
    - CTA
    - LSST
    - LOFAR
    - SKA
    - EGO-Virgo
    - KM3NeT
    - ELT
    - EST
    - HL-LHC
    - FAIR
    - CERN
    - ESO
    - JIVE
    - VO
    - EOSC
    - ESO
2. Domain category (single keywords):
    - `Astronomy`
    - `Astroparticle physics`
    - `Particle physics`
3. Notebooks category. At the moment only Jupyter notebooks are supported.
    - Add `jupyter-notebook` as keyword if you project is based on or contains jupyter notebooks
    - Do not add anything otherwise
 
Enrique Garcia's avatar
Enrique Garcia committed
60
 
Enrique Garcia's avatar
Enrique Garcia committed
61 62
The reason to add the above keywords is just for classification and findability purposes in the OSSR (the
 [ESCAPE2020 Zenodo community](https://zenodo.org/communities/escape2020) by other services such as the ESFRI Science Analysis Platform.
Enrique Garcia's avatar
Enrique Garcia committed
63
 
Enrique Garcia's avatar
Enrique Garcia committed
64
## Create a Zenodo metadata file from the a CodeMeta schema file
vuillaut's avatar
vuillaut committed
65

Enrique Garcia's avatar
Enrique Garcia committed
66
The zenodo repository does not accept codemeta metadata files yet. Meanwhile, the [codemeta2zenodo library](https://gitlab.in2p3.fr/escape2020/wp3/codemeta2zenodo) 
Enrique Garcia's avatar
Enrique Garcia committed
67 68
provides a simple tool to create a native Zenodo metadata file (`.zenodo.json`) from a `codemeta.json` file. To do so;

Enrique Garcia's avatar
Enrique Garcia committed
69
 1. Include a `codemeta.json` file to the root directory of your project.
Enrique Garcia's avatar
Enrique Garcia committed
70 71 72 73 74 75 76 77 78 79 80
 2. Install the `codemeta2zenodo` package;
```bash
 $ git clone https://gitlab.in2p3.fr/escape2020/wp3/codemeta2zenodo.git
 $ cd codemeta2zenodo
 $ pip install .
```
 3. And then just run
 ```bash
 $ codemeta2zenodo --codemeta_file codemeta.json
```

Enrique Garcia's avatar
Enrique Garcia committed
81 82 83
Also, you can check and use the [**online codemeta2zenodo**](https://escape2020.pages.in2p3.fr/wp3/codemeta2zenodo/codemeta2zenodo.html)
converter, based in the same library.

Enrique Garcia's avatar
Enrique Garcia committed
84
In case of doubts or problems, please [contact us](mailto:vuillaume@lapp.in2p3.fr;garcia@lapp.in2p3.fr).
vuillaut's avatar
vuillaut committed
85 86


Enrique Garcia's avatar
Enrique Garcia committed
87 88 89 90 91 92
**THIS STAGE IS RECOMMENDED, BUT NOT COMPULSORY FOR THE OSSR ONBOARDING.** 
 - If you have linked your GitLab project with Zenodo using the autonomous procedure that [we propose](
 https://escape2020.pages.in2p3.fr/wp3/ossr-pages/page/contribute/publish_in_repository/), this stage will be done automatically. 
 - If you are providing software via GitHub - and/or its [autonomous procedure](https://guides.github.com/activities/citable-code/) -, 
 this stage is not mandatory (but still recommended). GitHub will take care of fetching the metadata from the project directly. 

Enrique Garcia's avatar
Enrique Garcia committed
93
## Metadata schema templates
vuillaut's avatar
vuillaut committed
94

Enrique Garcia's avatar
Enrique Garcia committed
95
Inside the `codemeta_utils` directory you will find two template files with **the all the properties (terms) of the corresponding metadata schema context** 
Enrique Garcia's avatar
Enrique Garcia committed
96 97 98
 for both the CodeMeta metadata file and the Zenodo metadata file.
 
Feel free to create and incorporate the metadata files starting from these templates. However, please note that  
Enrique Garcia's avatar
Enrique Garcia committed
99 100
the final filenames **MUST** be either `codemeta.json` or `.zenodo.json` (note the `.` !). In case you do not fill or 
write nothing on any dictionary key field, take it out of the file.
vuillaut's avatar
vuillaut committed
101

Enrique Garcia's avatar
Enrique Garcia committed
102
In case of doubts please also check;
Enrique Garcia's avatar
Enrique Garcia committed
103
  - The [CodeMeta properties/terms description](https://codemeta.github.io/terms/) or,
Enrique Garcia's avatar
Enrique Garcia committed
104 105 106 107
  - the [`metadata representation`](https://developers.zenodo.org/#representation) allowed for the `.zenodo.json` metadata file.
  
  
### Extending the CodeMeta Context schema
vuillaut's avatar
vuillaut committed
108

Enrique Garcia's avatar
Enrique Garcia committed
109 110
In case you find that CodeMeta context does not describe deep enough your digital resource, you can extend the metadata 
context and combine it with all the terms available at [https://schema.org](https://schema.org/docs/full.html).
Enrique Garcia's avatar
Enrique Garcia committed
111 112 113 114 115 116 117
For this purpose, and following the [CodeMeta's developer guide](https://codemeta.github.io/developer-guide/);

   1. Modify the `"@Context"` key of the `codemeta.json` as; 
    
    "@context": ["https://raw.githubusercontent.com/codemeta/codemeta/2.0-rc/codemeta.jsonld", "http://schema.org/"]
     
   2. Include the desired terms / properties following the `schema.org` context.
Enrique Garcia's avatar
Enrique Garcia committed
118
   3. Contact us for a likely implementation into the OSSR environment ;-)
Enrique Garcia's avatar
Enrique Garcia committed
119 120


Enrique Garcia's avatar
Enrique Garcia committed
121 122
-----------------
-----------------
Enrique Garcia's avatar
Enrique Garcia committed
123

vuillaut's avatar
vuillaut committed
124

Enrique Garcia's avatar
Enrique Garcia committed
125
### How to automatise the upload of a GitLab project to Zenodo via the GitLab-CI
Enrique Garcia's avatar
Enrique Garcia committed
126

Enrique Garcia's avatar
Enrique Garcia committed
127 128 129 130
 - Add a `codemeta.js` file to your repository.
 - Link your GitLab project and your Zenodo accounts.
 - Add the following code snippet (Section 3. of the detailed tutorial) to the `.gitlab-ci.yml` file of your project and let the pipeline work !
 - Check the [detailed tutorial](https://escape2020.pages.in2p3.fr/wp3/ossr-pages/page/contribute/publish_tutorial/) for more details. 
Enrique Garcia's avatar
Enrique Garcia committed
131