README.md 5.17 KB
Newer Older
1
# template_project_escape 
2
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3884963.svg)](https://doi.org/10.5281/zenodo.3884963) 
3 4
[![pipeline status](https://gitlab.in2p3.fr/escape2020/escape/template_project_escape/badges/master/pipeline.svg)](
https://gitlab.in2p3.fr/escape2020/escape/template_project_escape/-/commits/master)
5 6
[![Build Status](https://travis-ci.com/garciagenrique/template_project_escape.svg?branch=master)](
https://travis-ci.com/garciagenrique/template_project_escape)
7
[![License: MIT](https://img.shields.io/badge/License-MIT-indigo.svg)](https://opensource.org/licenses/MIT)
Enrique Garcia's avatar
Enrique Garcia committed
8 9


Enrique Garcia's avatar
Enrique Garcia committed
10 11 12 13
<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
14
A simple template project to provide software to ESCAPE.
15

16 17
The repository shows the **basic documentation** that should be included within the project (following the 
[opensource guide](https://opensource.guide/starting-a-project/)):
18

19 20 21 22
* 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. 
23 24 25 26
* 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.
27
* The repository itself.
28

Enrique Garcia's avatar
style2  
Enrique Garcia committed
29
It would be highly suitable to include too:
30
   - A setup file as well as the basic commands to install the library (see below).
Enrique Garcia's avatar
Enrique Garcia committed
31
   - A `.gitignore` file.
32
   - Unitary and integration tests, and ideally a CI pipeline.
Enrique Garcia's avatar
Enrique Garcia committed
33
   
Enrique Garcia's avatar
Enrique Garcia committed
34 35
**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).
36

Enrique Garcia's avatar
Enrique Garcia committed
37
Take few minutes to check the [ESCAPE repository's guidelines](https://gitlab.in2p3.fr/escape2020/guidelines) too.
38

39
# Contributing guidelines for the ESCAPE repository
40

Enrique Garcia's avatar
Enrique Garcia committed
41 42
If you wish to provide software to the ESCAPE repository: 

43 44
 - You should ask developer access through the Gitlab interface and send an email to vuillaume [at] lapp.in2p3.fr with
  your institution email.
45

Enrique Garcia's avatar
Enrique Garcia committed
46
 - You will then be able to open a new project and transfer code.
Enrique Garcia's avatar
Enrique Garcia committed
47

48
 - All the code provided should be uploaded from the [Zenodo ESCAPE community](https://zenodo.org/communities/escape2020/). 
Enrique Garcia's avatar
Enrique Garcia committed
49

50 51 52
 - For a detailed explanation of how to submit a contribution to a project / repository (Fork, create a branch, make
  a pull request...), please check 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).
Enrique Garcia's avatar
Enrique Garcia committed
53

54 55 56
 - Once you are granted with developer access, you will be able to add a new blank project / import it (from other
  common repository managers, i.e., GitHub, GitLab, Bitbucket, Fogbugz...) to the
   [GitLab/ESCAPE](https://gitlab.in2p3.fr/escape2020) main page.
Enrique Garcia's avatar
Enrique Garcia committed
57

58 59 60
***PLEASE NOTE*** 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
61

62
# Singularity image container and CI/CD to Zenodo
Enrique Garcia's avatar
Enrique Garcia committed
63

64 65 66 67 68 69 70
An example of how to; 
 1. create a Singularity image / container of your code, 
 2. make it available as a downloadable artifact within your project and 
 3. add it to the ESCAPE community in the [Zenodo repository](https://zenodo.org/communities/escape2020), 
 
can be found in the `.gitlabci`, `.zenodoci` directories and in the `.gitlab-ci.yml` file. Please read carefully 
all the README files.  
71 72 73

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. 
Enrique Garcia's avatar
Enrique Garcia committed
74

75 76 77 78 79 80 81 82
# Installation

```sh
  $ git clone https://gitlab.in2p3.fr/escape2020/escape/template_project_escape.git
  $ cd template_project_escape
  $ python setup.py install
``` 

83
This is an easy method to install the current project. 
84 85 86
You can also check other more elaborated ways - generally for bigger repositories - here (e.g.,
 [cta-observatory/cta-lstchain](https://github.com/cta-observatory/cta-lstchain), 
 [cta-observatory/ctapipe](https://github.com/cta-observatory/ctapipe)).
87

Enrique Garcia's avatar
Enrique Garcia committed
88
# Citing 
Enrique Garcia's avatar
Enrique Garcia committed
89
In case of citing this repository, use the following DOI:
90
 - v2.0 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3884963.svg)](https://doi.org/10.5281/zenodo.3884963)
Enrique Garcia's avatar
Enrique Garcia committed
91

92 93 94 95 96
Do not forget to include your code / container into the [Zenodo ESCAPE community](https://zenodo.org/communities/escape2020/). 
 - ***Note that*** you will be able to assign a DOI in the moment you include your code/repository to Zenodo. 
 
Please check the licenses of the code within in the `.gitlabci`, `.zenodoci` directories before adding this template 
to your project.
97

Enrique Garcia's avatar
Enrique Garcia committed
98
# Report an issue / Ask a question
99
Use the [GitLab repository Issues](https://gitlab.in2p3.fr/escape2020/escape/template_project_escape/-/issues).
Enrique Garcia's avatar
Enrique Garcia committed
100 101 102

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