From fa3612d3fc78d0d88750278f825d0d0cd830e9da Mon Sep 17 00:00:00 2001 From: Mirek Kratochvil Date: Mon, 19 Jun 2023 11:29:06 +0200 Subject: [PATCH] remove the temporary codeCheck card --- cards/codeCheck.md | 279 --------------------------------------------- 1 file changed, 279 deletions(-) delete mode 100644 cards/codeCheck.md diff --git a/cards/codeCheck.md b/cards/codeCheck.md deleted file mode 100644 index 9b83915..0000000 --- a/cards/codeCheck.md +++ /dev/null @@ -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.