README.md 5.71 KB
Newer Older
1
# template_project_escape 
Enrique Garcia's avatar
Enrique Garcia committed
2
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.4923992.svg)](https://doi.org/10.5281/zenodo.4923992) 
3 4 5
[![pipeline status](https://gitlab.in2p3.fr/escape2020/wp3/template_project_escape/badges/master/pipeline.svg)](
https://gitlab.in2p3.fr/escape2020/wp3/template_project_escape/-/commits/master)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
6 7 8
[![Binder](https://mybinder.org/badge_logo.svg)](
https://mybinder.org/v2/gh/https%3A%2F%2Fgitlab.in2p3.fr%2Fescape2020%2Fwp3%2Ftemplate_project_escape/HEAD)

Enrique Garcia's avatar
Enrique Garcia committed
9 10


Enrique Garcia's avatar
Enrique Garcia committed
11 12 13 14
<p align="center">
   <img src="https://cdn.eso.org/images/large/ann18084a.jpg" width="640" height="453"/>
</p>

Enrique Garcia's avatar
Enrique Garcia committed
15
A simple template project to provide software to ESCAPE.
16

Enrique Garcia's avatar
Enrique Garcia committed
17
This repository shows the **basic content** that should be included in a project (following the 
18
[opensource guide](https://opensource.guide/starting-a-project/)):
19

20 21 22 23
* An [open source](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/licensing-a-repository#where-does-the-license-live-on-my-repository)
 **license**.
* A [**README** file](https://help.github.com/en/github/getting-started-with-github/create-a-repo#commit-your-first-change),
 similar to this one. 
24 25 26 27
* Contributing guidelines. 
    - See below the general guidelines for the ESCAPE repository.
* A [code of conduct](https://opensource.guide/code-of-conduct/).
    - Check why is a good idea to add one.
28
* The repository itself.
29

Enrique Garcia's avatar
style2  
Enrique Garcia committed
30
It would be highly suitable to include too:
31
   - A setup file as well as the basic commands to install the library (see below).
Enrique Garcia's avatar
Enrique Garcia committed
32
   - A `.gitignore` file.
33
   - Unitary and integration tests, and ideally a CI pipeline.
Enrique Garcia's avatar
Enrique Garcia committed
34
   
Enrique Garcia's avatar
Enrique Garcia committed
35 36
**Please feel free to clone / fork / template this project!** (For example, look to left of the 
`Clone or download` button in the [GitHub](https://github.com/garciagenrique/template_project_escape) site).
37

Enrique Garcia's avatar
Enrique Garcia committed
38 39 40 41 42 43
  - For a detailed explanation of how to submit a contribution to a project / repository (Fork, create a branch, make
  a pull request...), you can have a look to the [opensource guide](https://opensource.guide/how-to-contribute/#how-to-submit-a-contribution) 
  and/or the [git's documentation](https://git-scm.com/doc).
  - Not that if you have login GitLab by using the `[Shibbolenth]` service (eduGAIN, Fédération d'Identités 
  RENATER), you will need to [add a SSH key](https://gitlab.in2p3.fr/help/ssh/README#generating-a-new-ssh-key-pair) to 
  your GitLab profile if you want to 'push' your changes to the server. 
Enrique Garcia's avatar
Enrique Garcia committed
44

Enrique Garcia's avatar
Enrique Garcia committed
45
# Contribute to the ESCAPE OSSR
Enrique Garcia's avatar
Enrique Garcia committed
46

Enrique Garcia's avatar
Enrique Garcia committed
47
If you want to provide software to the ESCAPE repository: 
Enrique Garcia's avatar
Enrique Garcia committed
48

Enrique Garcia's avatar
Enrique Garcia committed
49 50 51
 - Check the [ESCAPE OSSR guidelines](https://escape2020.pages.in2p3.fr/wp3/ossr-pages/page/contribute/contribute_ossr/).
    - For ESCAPE members, follow the steps detailed in [the onboarding project](https://gitlab.in2p3.fr/escape2020/wp3/onboarding)
    to finalise your contribution and the same onboarding process.
Enrique Garcia's avatar
Enrique Garcia committed
52

Enrique Garcia's avatar
Enrique Garcia committed
53 54
 - All the code provided should be uploaded to the [Zenodo ESCAPE community](https://zenodo.org/communities/escape2020/).
 
55 56
 - Check the following [tutorial on how to publish content in Zenodo](https://escape2020.pages.in2p3.fr/wp3/ossr-pages/page/contribute/publish_tutorial/), 
   and how to automatise the upload of each new release of your project. 
Enrique Garcia's avatar
Enrique Garcia committed
57

58
# This project also includes
Enrique Garcia's avatar
Enrique Garcia committed
59

60 61 62
## 1. How to automatise the building of a Singularity image and upload it to Zenodo using the GitLab-CI

A working example of how to automatise the GitLab-CI to; 
63 64
 1. create a Singularity image / container of your code, 
 2. make it available as a downloadable artifact within your project and 
65
 3. upload it to the [ESCAPE OSSR](https://zenodo.org/communities/escape2020), 
66
 
67 68
can be found in the `.singularityci`, and `Singularity` directories and in the `.gitlab-ci.yml` file - the 
`build_singularity_image` stage. Please read carefully all the README files.  
69 70

For an easy example of how to create a Singularity receipt from scratch (and its corresponding container when executed),
71 72 73 74 75 76
please have a look to the `singularity_utils` directory.

## 2. How to automatise the building of a Docker container and upload it to the GitLab Container Registry

An example can be found in the `Docker` directory and in the `.gitlab-ci.yml` file -  the 
`build_docker_image` stage. 
Enrique Garcia's avatar
Enrique Garcia committed
77

Enrique Garcia's avatar
Enrique Garcia committed
78 79
# Install
Example of how to show installing instructions (and indeed the way to install this project).
80 81

```sh
82
  $ git clone https://gitlab.in2p3.fr/escape2020/wp3/template_project_escape.git
83
  $ cd template_project_escape
Enrique Garcia's avatar
Enrique Garcia committed
84
  $ pip install .
85 86
``` 

Enrique Garcia's avatar
Enrique Garcia committed
87
# Citing 
Enrique Garcia's avatar
Enrique Garcia committed
88 89
Example of citing (as well as the DOI to cite this project),

Enrique Garcia's avatar
Enrique Garcia committed
90
In case of citing this repository, use the following DOI:
Enrique Garcia's avatar
Enrique Garcia committed
91
 - v2.2 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.4923992.svg)](https://doi.org/10.5281/zenodo.4923992)
92
 - v2.1 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.4790629.svg)](https://doi.org/10.5281/zenodo.4790629)
93
 - v2.0 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3884963.svg)](https://doi.org/10.5281/zenodo.3884963)
94 95
 - v1.1 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3743490.svg)](https://doi.org/10.5281/zenodo.3743490)
 - v1.0 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3572655.svg)](https://doi.org/10.5281/zenodo.3572655) 
Enrique Garcia's avatar
Enrique Garcia committed
96

97
Do not forget to include your code / container into the [Zenodo ESCAPE community](https://zenodo.org/communities/escape2020/). 
98
 - ***Note that*** a DOI will be assigned in the moment create a new record/entry in Zenodo. 
99
 
100 101 102
# License 

Please check the licenses of the code within the `.singularityci` directory before adding this template 
103
to your project.
104

Enrique Garcia's avatar
Enrique Garcia committed
105
# Report an issue / Ask a question
106
Use the [GitLab repository Issues](https://gitlab.in2p3.fr/escape2020/wp3/template_project_escape/-/issues).
Enrique Garcia's avatar
Enrique Garcia committed
107 108 109

# Contact
Email to vuillaume [at] lapp.in2p3.fr / garcia [at] lapp.in2p3.fr.