Commit 63f9963f authored by Enrique Garcia's avatar Enrique Garcia
Browse files

add the zenodoci readme file, update repository README and some deco

parent 60a6971a
Pipeline #70291 passed with stages
in 11 minutes and 18 seconds
......@@ -11,13 +11,13 @@ The source code contained in this folder is based on the following
[gitlab-ci repository](https://gitlab.com/singularityhub/gitlab-ci). You can find a very didactic **tutorial** of how
to implement this code [here](https://vsoch.github.io/2018/gitlab-singularity-ci/).
Very summarised, this software (composed of the files within this directory **AND** the `gitlab-ci.yml` file in the
This software (composed of the files within this directory **AND** the `gitlab-ci.yml` file in the
root directory) provide the necessary tools to:
- Use a Singularity image stored in the SingularityHub to create a Singularity Container of your repository
(thus no need of having installed the Singularity program), and uploaded it directly to your GitLab repository.
- The Singularity receipt must be provided, of course.
- In case the container is too large (10 Gb total storage limit for a single GitLab project), you must pass
through a cloud service (various services examples are listed in the tutorial and the original repository).
through a cloud service (various examples of different services are shown in the tutorial and the original repository).
## License of the repository
The license of the 'parent' repository is `BSD 3-Clause License` ("BSD License 2.0", "Revised BSD License", "New BSD
......@@ -58,15 +58,16 @@ If this is the case, each file (based on or modified from its original) MUST con
> OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
### Specific case of the `template_project_repository`:
The `template_project_repository` contains code from different projects. This project can contain versions of different
projects because:
- Both parent projects are Open Source and their licenses are
[compatible](https://www.gnu.org/licenses/gpl-faq.html#WhatDoesCompatMean) (BSD 3-Clause and GPLv3).
- However, the GNU General Public License v3 is 'copyleft', meaning that the project resulting in the use of another
project with this license, MUST be licensed with the same license, i.e., GPLv3.
The `template_project_repository` contains code from different projects. This 'mixing' can be done because:
- Both 'parent' projects are Open Source.
- Both licenses, `BSD 3-Clause` and `GPLv3`, are [compatible](
https://www.gnu.org/licenses/gpl-faq.html#WhatDoesCompatMean); this means that source code distributed with a BSD
3-Clause license can be included within a project with a GPLv3 license:
- Note however that the GNU General Public License v3 is 'copyleft', meaning that the resulting project from the use
of any code licensed with GPLv3, must be distributed with the same license, thus GPLv3.
This is why the `template_project_repository` was re-licensed to GNU General Public License v 3.0, and each single
BSD-3 Clause file contains the original license.
This are the reasons why the `template_project_repository` is distributed with the GNU General Public License Version
3 and some files contain a BSD-3 Clause license.
**PLEASE TAKE THE TIME TO CHECK AND VERIFY LICENSES AND THEIR COMPATIBILITY**
**PLEASE TAKE THE TIME TO CHECK AND VERIFY LICENSES AND THEIR COMPATIBILITIES**
\ No newline at end of file
# .zenodoci
This
\ No newline at end of file
# .zenodoci
**PLEASE HAVE A LOOK TO THE LICENSING SECTION BELOW BEFORE IMPLEMENTING ANY PART OF THIS CODE INTO YOURS !!**
## Continuous Deployment to Zenodo
The source code contained in this folder is based on the
[zenodo-python repository](https://github.com/SiLeBAT/zenodo-python).
The software (composed of the `zenodolib.py` script) provides a library to handle the upload of a
specified file(s) to (sandbox)zenodo. Please **JUST** upload stable versions/releases of source code and/or images
containers!
By using the `zenodolib` library, as well as the created Singularity container (check the `.gitlabci` directory),
the second stage of the CI pipeline (see the `.gitlab-ci.yml` file) will:
- Either upload the desired file(s) to the ESCAPE community in Zenodo.
- Either upload a new version of an existing entry to Zenodo.
The `repository_information.json` file must be filled up before pushing to the project repository. Also, depending on
the case, the corresponding python script (`upload_new_deposit.py` or `upload_new_version_of_deposit.py`) must be
adapted and included into the `.gitlab-ci.yml` file with its corresponding arguments.
### Zenodo token & GitLab CI environment variable
To connect the GitLab repository with Zenodo in an autonomous way, a personal access token must be created. This token
is assign to a **single** Zenodo account, and it will allow to interact with (sandbox)zenodo through its
API. To create the token:
- Go to (sandbox)zenodo.org
- Account --> Applications --> Personal access token --> New token.
This token will be passed later in the continuous deployment stage of the CI/CD pipeline. For not sharing publicly
your personal token, you should create an environment variable in your GitLab repository. This way, the token could be used as a variable without
revealing its value. To create an an environment variable:
- Go to your GitLab repository.
- Settings --> CI/CD --> Variables --> Add variable --> Fill the fields --> Mask and protect the variable !
The environment variable will look like this:
```sh
$ python .zenodoci/upload_new_deposit.py -i build/Singularity -t $ZENODO_TOKEN
```
## License of the repository
The license of the 'parent' repository is `GNU GENERAL PUBLIC LICENSE Version 3` ("GNU GPL v3" or "GPLv3"). Before
implementing anything from the current or the original repository **please check that the license of the project
in which you are going to implement these source files is compatible with the GPLv3 license**.
If this is the case:
- The whole resulting project must be distributed with the same license, i.e., `GPLv3` and contain the license
and copyright notice (see the LICENSE file of the `template_project_repository`). GPLv3 is copyleft.
- Changes must be stated (here is an example of the kind of text that must be included in each modified file):
> This code is part of https://github.com/SiLeBAT/zenodo-python
>
> Copyright (c) 2015 Federal Institute for Risk Assessment (BfR), Germany
> This program is free software: you can redistribute it and/or modify
> it under the terms of the GNU General Public License as published by
> the Free Software Foundation, either version 3 of the License, or
> (at your option) any later version.
>
> This program is distributed in the hope that it will be useful,
> but WITHOUT ANY WARRANTY; without even the implied warranty of
> MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
> GNU General Public License for more details.
>
> You should have received a copy of the GNU General Public License
> along with this program. If not, see <http://www.gnu.org/licenses/>.
### Specific case of the `template_project_repository`:
The `template_project_repository` contains code from different projects. This 'mixing' can be done because:
- Both 'parent' projects are Open Source.
- Both licenses, `BSD 3-Clause` and `GPLv3`, are [compatible](
https://www.gnu.org/licenses/gpl-faq.html#WhatDoesCompatMean); this means that source code distributed with a BSD
3-Clause license can be included within a project with a GPLv3 license:
- Note however that the GNU General Public License v3 is 'copyleft', meaning that the resulting project from the use
of any code licensed with GPLv3, must be distributed with the same license, thus GPLv3.
This are the reasons why the `template_project_repository` is distributed with the GNU General Public License Version
3 and some files contain a BSD-3 Clause license.
**PLEASE TAKE THE TIME TO CHECK AND VERIFY LICENSES AND THEIR COMPATIBILITIES**
\ No newline at end of file
"""
Code from https://github.com/SiLeBAT/zenodo-python
stayed at commit
This code is part of https://github.com/SiLeBAT/zenodo-python,
stayed at commit 513b982c7bf949a96f8208e462c89475bc01d124
Copyright (c) 2015 Federal Institute for Risk Assessment (BfR), Germany
......@@ -16,9 +16,6 @@ GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
Contributors:
Department Biological Safety - BfR
"""
import enum
import json
......
# template_project_escape [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3572655.svg)](https://doi.org/10.5281/zenodo.3572655) [![Build Status](https://travis-ci.com/garciagenrique/template_project_escape.svg?branch=master)](https://travis-ci.com/garciagenrique/template_project_escape)
# template_project_escape
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3572655.svg)](https://doi.org/10.5281/zenodo.3572655)
[![Build Status](https://gitlab.in2p3.fr/escape2020/escape/template_project_escape/badges/master/pipeline.svg)](
https://gitlab.in2p3.fr/escape2020/escape/template_project_escape)
[![Build Status](https://travis-ci.com/garciagenrique/template_project_escape.svg?branch=master)](
https://travis-ci.com/garciagenrique/template_project_escape)
<p align="center">
......@@ -7,10 +12,13 @@
A simple template project to provide software to ESCAPE.
It shows the **basic documentation** a project should include, following the [opensource guide](https://opensource.guide/starting-a-project/):
It shows the **basic documentation** a project should include, following the
[opensource guide](https://opensource.guide/starting-a-project/):
* 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.
* 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.
* Contributing guidelines.
- See below the general guidelines for the ESCAPE repository.
* A [code of conduct](https://opensource.guide/code-of-conduct/).
......@@ -22,7 +30,8 @@ It would be highly suitable to include too:
- A .gitignore file.
- Unitary and integration tests.
**Please feel free to copy / base on / template this project!** (Look to left of the `Clone or download` button in the [GitHub](https://github.com/garciagenrique/template_project_escape) site).
**Please feel free to copy / base on / template this project!** (Look to left of the `Clone or download` button in the
[GitHub](https://github.com/garciagenrique/template_project_escape) site).
Take few minutes to check the [ESCAPE repository's guidelines](https://gitlab.in2p3.fr/escape2020/guidelines) too.
......@@ -30,21 +39,33 @@ Take few minutes to check the [ESCAPE repository's guidelines](https://gitlab.in
If you wish to provide software to the ESCAPE repository:
- You should ask developer access through the Gitlab interface and send an email to vuillaume [at] lapp.in2p3.fr with your institution email.
- You should ask developer access through the Gitlab interface and send an email to vuillaume [at] lapp.in2p3.fr with
your institution email.
- You will then be able to open a new project and transfer code.
- All the code provided should be uploaded from the [zenodo ESCAPE community](https://zenodo.org/communities/escape2020/).
- All the code provided should be uploaded from the [Zenodo ESCAPE community](https://zenodo.org/communities/escape2020/).
- 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).
- 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).
- 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.
- 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.
***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.
***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.
### Docker / containers
### Singularity image container and CI/CD to Zenodo
Documentation of how to create a Docker image / container of your code and add it to the ESCAPE repository and community is under construction.
The documentation of how to create a Singularity image / container of your code, upload it to your repository, and also 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.
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.
# Installation
......@@ -55,17 +76,22 @@ Documentation of how to create a Docker image / container of your code and add i
```
This is an easy method to install the library.
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)).
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)).
# Citing
In case of citing this repository, use the following DOI:
- v 1.0: [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3572655.svg)](https://doi.org/10.5281/zenodo.3572655)
Do not forget to include the code in 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.
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.
# Report an issue / Ask a question
Use [GitLab Issues](https://gitlab.in2p3.fr/groups/escape2020/-/issues).
Use the [GitLab repository Issues](https://gitlab.in2p3.fr/escape2020/escape/template_project_escape/-/issues).
# Contact
Email to vuillaume [at] lapp.in2p3.fr / garcia [at] lapp.in2p3.fr.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment