diff options
Diffstat (limited to 'cards')
| -rw-r--r-- | cards/codeCheck.md | 276 | ||||
| -rw-r--r-- | cards/index.md | 8 |
2 files changed, 284 insertions, 0 deletions
diff --git a/cards/codeCheck.md b/cards/codeCheck.md new file mode 100644 index 0000000..c938f87 --- /dev/null +++ b/cards/codeCheck.md @@ -0,0 +1,276 @@ +--- +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 + - code/conventions +--- + +# 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. diff --git a/cards/index.md b/cards/index.md new file mode 100644 index 0000000..c1ebd4a --- /dev/null +++ b/cards/index.md @@ -0,0 +1,8 @@ +--- +mount: / +title: How-To Cards main page +--- + +# Index page + +hello everyone! |