remove the temporary codeCheck card
This commit is contained in:
Mirek Kratochvil
parent
debe5453ed
commit
fa3612d3fc
|
|
@ -1,279 +0,0 @@
|
||||||
---
|
|
||||||
title: Code check
|
|
||||||
mount: publication/ppc/code-check
|
|
||||||
redirects:
|
|
||||||
- publication:codeCheck
|
|
||||||
- cards/publication-ppc:codeCheck
|
|
||||||
- internal/cards/publication-ppc:codeCheck
|
|
||||||
- publication-ppc/codeCheck
|
|
||||||
- internal/internal/publication-ppc/codeCheck
|
|
||||||
- cards/publication:codeCheck
|
|
||||||
- internal/cards/publication:codeCheck
|
|
||||||
- publication/codeCheck
|
|
||||||
- internal/internal/publication/codeCheck
|
|
||||||
tags:
|
|
||||||
- publication/ppc/code
|
|
||||||
- it/license
|
|
||||||
toc: 2
|
|
||||||
---
|
|
||||||
|
|
||||||
# How-to: Pass a PPC code check
|
|
||||||
|
|
||||||
The code part of the
|
|
||||||
[pre-publication checks](/?publication:prePublicationCheck)
|
|
||||||
is supposed mainly to check the compliance of the research with the
|
|
||||||
[LCSB code policy](/?qms:LCSB-POL-BIC-07)
|
|
||||||
and the re-usability of the research for the others, mainly enabled by licensing.
|
|
||||||
|
|
||||||
### What is checked within the code check?
|
|
||||||
|
|
||||||
To successfully pass the code check, you need to fulfill 3 main requirements on
|
|
||||||
the code:
|
|
||||||
|
|
||||||
- **Code deposition:** Any code associated to the publication is archived in a
|
|
||||||
way that it will stay accessible for the LCSB.
|
|
||||||
- **Minimal documentation:** The code has a minimal `README` file attached,
|
|
||||||
which documents the code purpose and its basic use required to reproduce the
|
|
||||||
results.
|
|
||||||
- **Licensing requirements:** The license of the code is compatible with the
|
|
||||||
licenses of the dependencies (such as various libraries). If the code is
|
|
||||||
public, the license file must be present to clarify the code use conditions.
|
|
||||||
|
|
||||||
### What is irrelevant to the code check?
|
|
||||||
|
|
||||||
The code check does **not** evaluate the following properties of the code, as
|
|
||||||
they are not implied by the code policy:
|
|
||||||
|
|
||||||
- Open-source code publication. It is **not required** to make your code public
|
|
||||||
in order to pass the code check. PPC coaches may detect a situation when
|
|
||||||
open-sourcing of the code might be viable, in which case they will recommend
|
|
||||||
(but never mandate) the code publication.
|
|
||||||
- Code quality. Code check will **not** evaluate advanced aspects of the code
|
|
||||||
apart from the basic reproducibility and readability that is implied by the
|
|
||||||
presence of the `README`, and code quality has **no** impact on the result of
|
|
||||||
code check. In case of serious code reusability flaws, PPC coaches may
|
|
||||||
recommend best way to make the code more useful for the users, but will not
|
|
||||||
require fixing the code.
|
|
||||||
|
|
||||||
## Code check in 3 steps
|
|
||||||
|
|
||||||
### Step 1: Move your code to the correct place
|
|
||||||
|
|
||||||
Your code repository must be stored in a common
|
|
||||||
[GitLab group that belongs to your research group](/?integrity:gitlabGroups)
|
|
||||||
(and is typically managed by your PI). Examples of such groups include e.g. the
|
|
||||||
ones by [MFN](https://gitlab.lcsb.uni.lu/MFN) and
|
|
||||||
[TNG](https://gitlab.lcsb.uni.lu/TNG). Your project
|
|
||||||
should **not** be deposited in the "personal" namespace, such as at
|
|
||||||
[`gitlab.lcsb.uni.lu/firstname.lastname/some-hidden-project`](https://gitlab.lcsb.uni.lu/firstname.lastname/some-hidden-project),
|
|
||||||
as this restricts the availability of your code for others.
|
|
||||||
|
|
||||||
To make sure the project is in the right group,
|
|
||||||
|
|
||||||
- when creating a [new
|
|
||||||
project](https://gitlab.lcsb.uni.lu/projects/new#blank_project), find the
|
|
||||||
matching group in a dropdown below **Project URL**, in the field marked with
|
|
||||||
*Pick a group or namespace*.
|
|
||||||
- if your project already exists, you can [transfer it to the desired
|
|
||||||
group](https://docs.gitlab.com/ee/tutorials/move_personal_project_to_a_group.html#tutorial-move-your-personal-project-to-a-group)
|
|
||||||
by clicking **Setting** (in the menu on the left) → **General** →
|
|
||||||
**Advanced** (all the way below) → **Transfer project**; there you select the
|
|
||||||
target group in the box labeled with **Select a new namespace**.
|
|
||||||
|
|
||||||
For all projects, make sure that the project visibility matches the expectations:
|
|
||||||
|
|
||||||
- **Closed-source projects** should display a small padlock 🔒 next to the
|
|
||||||
project title on the main project page, meaning the access is restricted
|
|
||||||
- **Open-source project** should display a small globe icon 🌐, meaning the
|
|
||||||
project is accessible globally.
|
|
||||||
|
|
||||||
The
|
|
||||||
[project visibility can be changed](https://docs.gitlab.com/ee/user/public_access.html#change-project-visibility)
|
|
||||||
from the menu on the left, via **Settings** → **General** → **Visibility,
|
|
||||||
project features, permissions** → **Project visibility**.
|
|
||||||
|
|
||||||
Troubleshooting:
|
|
||||||
|
|
||||||
- If you do not know what group to choose and there is no information about
|
|
||||||
your group in [the list](/?integrity:gitlabGroups),
|
|
||||||
ask your PI.
|
|
||||||
- If your research group has no namespace in GitLab yet, ask your PI or the R3
|
|
||||||
team to create one for you.
|
|
||||||
- If you want to host your code somewhere else (e.g., on GitHub), consult the
|
|
||||||
[code policy](/?qms:LCSB-POL-BIC-07) for detailed
|
|
||||||
conditions. Most notably, you will need an approval from your PI.
|
|
||||||
|
|
||||||
R3 team may be contacted using [lcsb-r3@uni.lu](mailto:lcsb-r3@uni.lu).
|
|
||||||
|
|
||||||
### Step 2: Write a simple `README`
|
|
||||||
|
|
||||||
`README` is a plain text or markdown file (`README.md` in that case) which sits
|
|
||||||
in the root of the repository and answers the following questions to the
|
|
||||||
potential code users:
|
|
||||||
|
|
||||||
- what does the code do?
|
|
||||||
- what are the expected inputs and outputs?
|
|
||||||
- what algorithms does it run, and for what purpose?
|
|
||||||
- what is required to run the code?
|
|
||||||
- what commands the user has to type?
|
|
||||||
- what other software (dependencies) the user has to install before running
|
|
||||||
the code, and how?
|
|
||||||
- if applicable, what research (or publication) does the code support?
|
|
||||||
|
|
||||||
A sufficient `README` file may be as short as 2 sentences that briefly clarify
|
|
||||||
the above, but it is recommended to be slightly more verbose. We recommend to
|
|
||||||
follow the example of existing repositories with good `README` files:
|
|
||||||
|
|
||||||
- Supporting code for a computational publication:
|
|
||||||
- [gitlab.lcsb.uni.lu/MFN/camesyn/comparison-protocols](https://gitlab.lcsb.uni.lu/MFN/camesyn/comparison-protocols)
|
|
||||||
- [gitlab.lcsb.uni.lu/SCG/cowwan](https://gitlab.lcsb.uni.lu/SCG/cowwan)
|
|
||||||
- [gitlab.lcsb.uni.lu/ESB/archaea_in_gut](https://gitlab.lcsb.uni.lu/ESB/archaea_in_gut)
|
|
||||||
- [gitlab.lcsb.uni.lu/lcsb-biocore/boolean-modelling-of-pd-paper](https://gitlab.lcsb.uni.lu/lcsb-biocore/boolean-modelling-of-pd-paper)
|
|
||||||
- Internal tooling:
|
|
||||||
- [gitlab.lcsb.uni.lu/R3/outreach/templates/presentations/markdown](https://gitlab.lcsb.uni.lu/R3/outreach/templates/presentations/markdown)
|
|
||||||
- Open-source software:
|
|
||||||
- [gitlab.lcsb.uni.lu/minerva/automap](https://gitlab.lcsb.uni.lu/minerva/automap)
|
|
||||||
- [gitlab.lcsb.uni.lu/lcsb-biocore/COBREXA.jl](https://gitlab.lcsb.uni.lu/lcsb-biocore/COBREXA.jl)
|
|
||||||
- [gitlab.lcsb.uni.lu/lcsb-biocore/SBML.jl](https://gitlab.lcsb.uni.lu/lcsb-biocore/SBML.jl)
|
|
||||||
- [gitlab.lcsb.uni.lu/eci/shinyscreen](https://gitlab.lcsb.uni.lu/eci/shinyscreen)
|
|
||||||
- [gitlab.lcsb.uni.lu/CBG/RNetDys](https://gitlab.lcsb.uni.lu/CBG/RNetDys)
|
|
||||||
- [gitlab.lcsb.uni.lu/bds/transreg](https://gitlab.lcsb.uni.lu/bds/transreg)
|
|
||||||
|
|
||||||
Especially for open source projects, remember that a nice `README` file is one
|
|
||||||
of the main main decisive factors for the users to try using your project
|
|
||||||
(eventually generating citations of your research). Consider adding the
|
|
||||||
following to your `README`s to increase both their appearance and practical
|
|
||||||
value:
|
|
||||||
|
|
||||||
- [badges for CI, documentation, and many other things](https://shields.io/)
|
|
||||||
- institute, university, lab or project acknowledgements and logos
|
|
||||||
- simple code example to run the library
|
|
||||||
- links to dockerized software versions
|
|
||||||
- short copyable scripts that install the software
|
|
||||||
- links to use-cases
|
|
||||||
- a nice, self-explanatory picture of the result
|
|
||||||
- link to a comprehensive documentation, if available
|
|
||||||
- link to the publication, possibly accompanied by a preprint link and a
|
|
||||||
[`CITATION`](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files)
|
|
||||||
file
|
|
||||||
|
|
||||||
|
|
||||||
### Step 3: Add a license
|
|
||||||
|
|
||||||
The choice of code sharing policy and the license is the responsibility of your
|
|
||||||
PI. If you are not sure what your license should be, ask your PI. You can talk
|
|
||||||
to R3 team ([lcsb-r3@uni.lu](mailto:lcsb-r3@uni.lu)), TTO
|
|
||||||
([lcsb-innovation@uni.lu](mailto:lcsb-innovation@uni.lu)), and possibly the
|
|
||||||
legal support ([lcsb-legal@uni.lu](mailto:lcsb-legal@uni.lu)) for
|
|
||||||
recommendations.
|
|
||||||
|
|
||||||
The main considerations on open- vs. closed-sourcing the code (which have
|
|
||||||
licensing implications) are as follows:
|
|
||||||
|
|
||||||
- **Open-source code:** Open-sourcing the code related to your publication is
|
|
||||||
usually recommended (also, it is very welcome by journals and we have seen
|
|
||||||
several cases of reviewers rejecting a paper based on code unavailability).
|
|
||||||
You may pick any OSS-compliant license that is compatible with your code's
|
|
||||||
dependencies. Remember that the code publication and the license choice must
|
|
||||||
be approved by your PI. Preferably, aim for using licenses like Apache2.0
|
|
||||||
(recommended as a default for open-source projects), MIT, or GPL.
|
|
||||||
- **Closed-source code:** Closed-source code is possible, and is usually a good
|
|
||||||
choice for internal projects and projects that involve a lot of manipulation
|
|
||||||
of sensitive data (where code may already leak sensitive information).
|
|
||||||
Initially the code does not require any license treatment. When you later
|
|
||||||
need to share the code, it is recommended to attach short copyright notices.
|
|
||||||
(See the FAQ section below.)
|
|
||||||
- **Potentially patentable code:** With all projects it is recommended to
|
|
||||||
**delay open-sourcing the code AFTER the TTO has examined the potential
|
|
||||||
commercial value of the code**, even after the PI's approval of publication.
|
|
||||||
Algorithms and pipelines may be patented, and publishing the code prematurely
|
|
||||||
typically makes any patenting impossible. Ask the TTO **before** publishing
|
|
||||||
the code if you have even the slightest suspicion that the code might be
|
|
||||||
commercially useful.
|
|
||||||
|
|
||||||
When the license is decided, you simply add a file `LICENSE` or `LICENSE.md` in
|
|
||||||
the root of your repository, and copypaste the desired license into it. The
|
|
||||||
license text may be obtained from OSS licensing websites
|
|
||||||
([choosealicense.com](https://choosealicense.com/),
|
|
||||||
[GitHub](https://github.com/IQAndreas/markdown-licenses)) or copied from other
|
|
||||||
projects. Examples of correct LICENSE applications may be found among the
|
|
||||||
open-source projects listed above.
|
|
||||||
|
|
||||||
**Hint**: If you are adding the license file in GitLab, after clicking the big
|
|
||||||
"plus" button, following with *New file* button and filling in the name of the
|
|
||||||
file `LICENSE`, GitLab will offer you a drop-down with several prepared
|
|
||||||
open-source licenses. This way you do not need to copypaste the whole license
|
|
||||||
text manually. (Sometimes, GitLab will even directly offer a big *Add LICENSE*
|
|
||||||
button, which does the same.)
|
|
||||||
|
|
||||||
## Commonly asked&answered questions (FAQ)
|
|
||||||
|
|
||||||
### Do I need to upload my code to GitLab even if it is not supposed to be published?
|
|
||||||
|
|
||||||
Yes. Unless treated otherwise with a signed contract with the University, all
|
|
||||||
code you produce within the LCSB is a research output that belongs to the
|
|
||||||
University and must be deposited for **internal** archival, as required by the
|
|
||||||
code policy. As explained above, uploading to GitLab does not imply that the
|
|
||||||
code would have to be published (i.e., open-sourced) -- the repository with the
|
|
||||||
code can stay private (and closed-source) forever.
|
|
||||||
|
|
||||||
Notably, this also concerns code that is not associated to any publication
|
|
||||||
output.
|
|
||||||
|
|
||||||
### How do I handle non-public code that is supposed to be disclosed upon request?
|
|
||||||
|
|
||||||
There are no standard guidelines, because the specific situation and
|
|
||||||
requirements vary a lot between cases. It is advisable to contact the R3
|
|
||||||
team and the TTO office to discuss the current applicable policies and
|
|
||||||
recommendations. At the same time, you should understand that the code
|
|
||||||
availability "upon request" **creates an additional significant long-term
|
|
||||||
administrative and legal load on LCSB staff, and should be avoided unless
|
|
||||||
absolutely necessary**.
|
|
||||||
|
|
||||||
The general advice for such cases includes the following:
|
|
||||||
|
|
||||||
- If the code is not supposed to be circulated publicly, add a **clear
|
|
||||||
copyright statement** to the header of each source code file (as a code
|
|
||||||
comment) and to the separate `LICENSE` file in the root of the repository.
|
|
||||||
The copyright notice for the code header comments and a closed-source LICENSE
|
|
||||||
file may look simply as follows:
|
|
||||||
```
|
|
||||||
Copyright (c) 2022-2023 University of Luxembourg; all rights reserved.
|
|
||||||
```
|
|
||||||
- If you are sharing the code as a response to a request, you may demand the
|
|
||||||
third party to sign a non-disclosure agreement (NDA) and possibly other
|
|
||||||
contracts (depending on the specific case) before receiving the code.
|
|
||||||
- To ensure on-demand code availability in the future, archive the code into a
|
|
||||||
single "bundle" (such as a `zip` file), and treat this archive as non-public
|
|
||||||
dataset that is shared upon request: Deposit it to a suitable archival medium
|
|
||||||
(such as GitLab and Atlas), make a record in
|
|
||||||
[DAISY](https://daisy.lcsb.uni.lu/), and add an "availability upon request"
|
|
||||||
statement that is compliant with the data check. Most notably, the code
|
|
||||||
contact must **not** point to a single person, but to a sustainable LCSB
|
|
||||||
service that manages the requests (such as TTO or LCSB data stewards).
|
|
||||||
- The code disclosure may be limited because the code implicitly contains
|
|
||||||
sensitive data, for example because the programs include very detailed
|
|
||||||
handling of sensitive datasets. In that case, the code itself must be
|
|
||||||
additionally treated as sensitive data, as regulated by the
|
|
||||||
[existing policies](/cards#qms).
|
|
||||||
|
|
||||||
### Can I pass the code check if I want to publish the code only after the paper is accepted?
|
|
||||||
|
|
||||||
Yes, but you will have to provide another way for the PPC coaches to have a
|
|
||||||
look at your code.
|
|
||||||
|
|
||||||
Typically, the coaches may ask for temporary access to the GitLab repository.
|
|
||||||
You may
|
|
||||||
[add the code coach to your GitLab project](https://docs.gitlab.com/ee/user/project/members/#add-users-to-a-project)
|
|
||||||
using **Project information** → **Members** → **Invite members**. You must
|
|
||||||
select at least the **Reporter** role, because the guest role does not offer
|
|
||||||
access to the actual code. To simplify things, you may add an access expiration
|
|
||||||
date (but please allow a week or two for possible later checks).
|
|
||||||
|
|
||||||
In cases when adding members to your repository is impractical or impossible,
|
|
||||||
it is also viable to arrange a short meeting with the PPC coaches to check the
|
|
||||||
basic requirements together.
|
|
||||||
|
|
||||||
**If your code is subject to non-disclosure,** strict closed-source copyright or
|
|
||||||
contains sensitive or secret information, please notify the PPC coaches in
|
|
||||||
advance, so that they use appropriate security measures.
|
|
||||||
Loading…
Reference in a new issue