README.md 7.37 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>

Vuillaume's avatar
Vuillaume committed
15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
# Content

 - [About this project](#about-this-project)
 - [Licensing](#license)
 - [Contribute to the ESCAPE OSSR](#contribute-to-the-escape-ossr)
 - [Install](#install)
 - [Report an issue or ask a question](#report-an-issue--ask-a-question)
 - [Contact](#contact)
 - [Citing this project](#citing)
 - [Examples contained in this project](#examples-contained-in-the-project)
      - [Automatise building Singularity images using CI/CD](#1-how-to-automatise-the-building-of-a-singularity-image-and-upload-it-to-zenodo-using-the-gitlab-ci)
      - [Automatise building Docker containers using CI/CD](#2-how-to-automatise-the-building-of-a-docker-container-and-upload-it-to-the-gitlab-container-registry) 
 

# About this project

Enrique Garcia's avatar
Enrique Garcia committed
31
A simple template project to provide software to ESCAPE.
32

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

36 37 38 39
* 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. 
40 41 42 43
* 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.
44
* The repository itself.
45

Enrique Garcia's avatar
style2  
Enrique Garcia committed
46
It would be highly suitable to include too:
47
   - A setup file as well as the basic commands to install the library (see below).
Enrique Garcia's avatar
Enrique Garcia committed
48
   - A `.gitignore` file.
49
   - Unitary and integration tests, and ideally a CI pipeline.
Enrique Garcia's avatar
Enrique Garcia committed
50
   
Enrique Garcia's avatar
Enrique Garcia committed
51 52
**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).
53

Enrique Garcia's avatar
Enrique Garcia committed
54 55 56 57 58 59
  - 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
60

Vuillaume's avatar
Vuillaume committed
61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80
# License 

Portions of this code are based on the `GitLab-CI` project ([repository link](https://gitlab.com/singularityhub/gitlab-ci), 
[Zenodo link and DOI](https://zenodo.org/record/3834833)) held by a 
[`BSD 3-Clause License`](https://opensource.org/licenses/BSD-3-Clause). You can check the complete license text 
[here](https://gitlab.com/singularityhub/gitlab-ci/-/blob/master/LICENSE).

## License of the `template_project_repository`:

The `template_project_repository` contains code from a third party project. This 'mixing' can be done because:
 - Both 'parent' projects are Open Source.
 - None of the original licenses are copy-left.
 - Both `BSD 3-Clause` and `MIT`, are permissive licenses. This means that source code distributed with 
 a BSD 3-Clause license can be included in a project with a MIT license and be re-distributed under `MIT`:
    - Note however, that the **original licenses** must be included in the resulting project and mentioned in the 
    LICENSE/documentation files.  

**PLEASE TAKE THE TIME TO CHECK AND VERIFY LICENSES AND THEIR COMPATIBILITIES** 


Enrique Garcia's avatar
Enrique Garcia committed
81
# Contribute to the ESCAPE OSSR
Enrique Garcia's avatar
Enrique Garcia committed
82

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

Enrique Garcia's avatar
Enrique Garcia committed
85 86 87
 - 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
88

Enrique Garcia's avatar
Enrique Garcia committed
89 90
 - All the code provided should be uploaded to the [Zenodo ESCAPE community](https://zenodo.org/communities/escape2020/).
 
91 92
 - 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
93

Enrique Garcia's avatar
Enrique Garcia committed
94

Enrique Garcia's avatar
Enrique Garcia committed
95 96
# Install
Example of how to show installing instructions (and indeed the way to install this project).
97 98

```sh
99
  $ git clone https://gitlab.in2p3.fr/escape2020/wp3/template_project_escape.git
100
  $ cd template_project_escape
Enrique Garcia's avatar
Enrique Garcia committed
101
  $ pip install .
102 103
``` 

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

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

Enrique Garcia's avatar
Enrique Garcia committed
110
# Citing 
Enrique Garcia's avatar
Enrique Garcia committed
111 112
Example of citing (as well as the DOI to cite this project),

Enrique Garcia's avatar
Enrique Garcia committed
113
In case of citing this repository, use the following DOI:
Enrique Garcia's avatar
Enrique Garcia committed
114
 - v2.2 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.4923992.svg)](https://doi.org/10.5281/zenodo.4923992)
115
 - v2.1 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.4790629.svg)](https://doi.org/10.5281/zenodo.4790629)
116
 - v2.0 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3884963.svg)](https://doi.org/10.5281/zenodo.3884963)
117 118
 - 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
119

120
Do not forget to include your code / container into the [Zenodo ESCAPE community](https://zenodo.org/communities/escape2020/). 
121
 - ***Note that*** a DOI will be assigned in the moment create a new record/entry in Zenodo. 
122
 
123

Vuillaume's avatar
Vuillaume committed
124
# Examples contained in this project
125

Vuillaume's avatar
Vuillaume committed
126
## 1. How to automatise the building of a Singularity image and upload it to Zenodo using the GitLab-CI
Enrique Garcia's avatar
Enrique Garcia committed
127

Vuillaume's avatar
Vuillaume committed
128 129 130 131 132 133 134 135 136 137 138 139 140 141 142
A working example of how to automatise the GitLab-CI to; 
 1. create a Singularity image / container of your code, 
 2. make it available as a downloadable artifact within your project and 
 3. upload it to the [ESCAPE OSSR](https://zenodo.org/communities/escape2020), 
 
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.  

For an easy example of how to create a Singularity receipt from scratch (and its corresponding container when executed),
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.