diff --git a/docs/adding_software/contribution_policy.md b/docs/adding_software/contribution_policy.md index b7c658fc5..a4a4d5c4f 100644 --- a/docs/adding_software/contribution_policy.md +++ b/docs/adding_software/contribution_policy.md @@ -1,3 +1,141 @@ # Contribution policy -(coming soon) +*(version v0.1.0 - updated 9 Nov 2023)* + +!!! note + + This policy is subject to change, please check back regularly. + +## Purpose + +The purpose of this contribution policy is to provide guidelines for [adding software](opening_pr.md) to EESSI. + +It informs about what requirements must be met in order for software to be eligible for inclusion +in the EESSI software layer. + +## Requirements + +The following requirements must be taken into account when adding software to EESSI. + +Note that additional restrictions may apply in specific cases that are currently not covered explicitly by this policy. + +--- + +### i) Open source software { #open_source_software } + +Only **freely redistributable software** can be added to the EESSI repository, +and we strongly prefer including only **open source software** in EESSI. + +Make sure that you are aware of the relevant software licenses, +and that redistribution of the software you want to add to EESSI is allowed. + +For more information about a specific software license, +see the [SPDX license list](https://spdx.org/licenses/). + +!!! note + + We intend to automatically verify that this requirement is met, + by requiring that the [SPDX license identifier](https://spdx.dev/ids/) is provided + for all software included in EESSI. + + +--- + +### ii) Built by the bot { #built_by_bot } + +All software included in the EESSI repository *must* be **built autonomously** by [our bot :robot:](../bot.md). + +For more information, see our [semi-automatic software installation procedure](building_software.md). + + +--- + +### iii) Built and installed with EasyBuild { #easybuild } + +We currently require that all software installations in EESSI are +**built and installed using EasyBuild**. + +We strongly prefer that the [*latest release of EasyBuild*](https://pypi.org/project/easybuild/) +that is available at the time is used to add software to EESSI. + +The use of [`--from-pr`](https://docs.easybuild.io/integration-with-github/#github_from_pr) and +[`--include-easyblocks-from-pr`](https://docs.easybuild.io/integration-with-github/#github_include_easyblocks_from_pr) +to pull in changes to EasyBuild that are required to make the installation work correctly +in EESSI is allowed, but only if that is strictly required +(that is, if those changes are not included yet in the latest EasyBuild release). + + +--- + +### iv) Supported compiler toolchain { #supported_toolchain } + +A **[compiler toolchain](https://docs.easybuild.io/terminology/#toolchains) that is still supported** +by the latest EasyBuild release *must* be used for building the software. + +For more information on supported toolchains, +see the [EasyBuild toolchain support policy](https://docs.easybuild.io/policies/toolchains). + + +--- + +### v) Recent toolchain versions { #recent_toolchains } + +We strongly prefer adding software to EESSI that was built with a **recent compiler toolchain**. + +When adding software to a particular version of EESSI, +you should *use a toolchain version that is already installed*. + +If you would like to see an additional toolchain version being added to a particular version of EESSI, +please [open a support request](../support.md) for this, and motivate your request. + +--- + +### vi) Recent software versions { #recent_software_versions } + +We strongly prefer adding sufficiently **recent software versions** to EESSI. + +If you would like to add older software versions, please clearly motivate the need for this +in your contribution. + + +--- + +### vii) CPU targets { #cpu_targets } + +Software that is added to EESSI *should* **work on all [supported CPU targets](../software_layer/cpu_targets.md)**. + +Exceptions to this requirement are allowed if technical problems that can not be resolved with reasonable effort +prevent the installation of the software for specific CPU targets. + + +--- + +### viii) Testing { #testing } + +We should be able to test the software installations via the [EESSI test suite](../test-suite/index.md), +in particular for software applications and user-facing tools. + +Ideally one or more tests are available that verify that the software is functionally correct, +and that it (still) performs well. + +Tests that are run during the software installation procedure as performed by EasyBuild *must* pass. +Exceptions can be made if only a small subset of tests fail for specific CPU targets, +as long as these exceptions are tracked and an effort is made to assess the impact of those failing tests. + +It should be possible to run a minimal *smoke test* for the software included in EESSI, +for example using EasyBuild's `--sanity-check-only` feature. + +!!! note + + The [EESSI test suite](https://github.com/EESSI/test-suite) is still in active development, + and currently only has a minimal set of tests available. + + When the test suite is more mature, this requirement will be enforced more strictly. + +--- + +## Changelog + +### v0.1.0 (9 Nov 2023) + +- initial contribution policy diff --git a/docs/adding_software/opening_pr.md b/docs/adding_software/opening_pr.md index ce82b68f0..0603966e3 100644 --- a/docs/adding_software/opening_pr.md +++ b/docs/adding_software/opening_pr.md @@ -11,6 +11,10 @@ To add software to EESSI, you should go through the semi-automatic software inst * 3) Instructing the [bot :robot:](../bot.md) to deploy the built software for ingestion into the EESSI repository; * 4) Merging the pull request once CI indicates that the software has been ingested. :white_check_mark: +!!! warning + + Make sure you are also aware of our [contribution policy](contribution_policy.md) when adding software to EESSI. + ### Preparation Before you can make a pull request to the [software-layer](https://github.com/EESSI/software-layer), diff --git a/docs/getting_access/eessi_container.md b/docs/getting_access/eessi_container.md index 78b9b1f5f..04c73c867 100644 --- a/docs/getting_access/eessi_container.md +++ b/docs/getting_access/eessi_container.md @@ -53,7 +53,7 @@ Apptainer> beginning with `CernVM-FS: ` have been printed after the first prompt `Apptainer> ` was shown. -To start using EESSI, see [Using EESSI/Setting up your environment](../../using_eessi/setting_up_environment). +To start using EESSI, see [Using EESSI/Setting up your environment](../using_eessi/setting_up_environment.md). ## Help for `eessi_container.sh` @@ -346,7 +346,7 @@ parsing command line arguments. For example, ## Running EESSI demos For examples of scripts that use the software provided by EESSI, -see [Running EESSI demos](../../using_eessi/eessi_demos). +see [Running EESSI demos](../using_eessi/eessi_demos.md). ## Launching containers more quickly Subsequent runs of `eessi_container.sh` may reuse temporary data of a previous diff --git a/docs/getting_access/is_eessi_accessible.md b/docs/getting_access/is_eessi_accessible.md index 8dc013ae4..218e8219b 100644 --- a/docs/getting_access/is_eessi_accessible.md +++ b/docs/getting_access/is_eessi_accessible.md @@ -1,7 +1,7 @@ # Is EESSI accessible? -EESSI can be accessed via [a native (CernVM-FS) installation](../native_installation), -or via [a container that includes CernVM-FS](../eessi_container). +EESSI can be accessed via [a native (CernVM-FS) installation](native_installation.md), +or via [a container that includes CernVM-FS](eessi_container.md). Before you look into these options, check if EESSI is already accessible on your system. @@ -21,7 +21,7 @@ host_injections latest versions ``` For starting to use EESSI, continue reading about -[Setting up environment](../../using_eessi/setting_up_environment). +[Setting up environment](../using_eessi/setting_up_environment.md). If you see an error message as shown below, **EESSI is not yet accessible on your system**. @@ -30,5 +30,5 @@ ls: /cvmfs/pilot.eessi-hpc.org: No such file or directory ``` No worries, you don't need to be a :mage: to get access to EESSI. -Continue reading about the [Native installation](../native_installation) of EESSI, -or access via the [EESSI container](../eessi_container). +Continue reading about the [Native installation](native_installation.md) of EESSI, +or access via the [EESSI container](eessi_container.md). diff --git a/docs/getting_access/native_installation.md b/docs/getting_access/native_installation.md index 47380fb35..b5cd197f0 100644 --- a/docs/getting_access/native_installation.md +++ b/docs/getting_access/native_installation.md @@ -1,7 +1,7 @@ # Native installation Setting up native access to EESSI, that is a system-wide deployment that does not require workarounds like -[using a container](../eessi_container), requires the installation and configuration of [CernVM-FS](https://cernvm.cern.ch/fs). +[using a container](eessi_container.md), requires the installation and configuration of [CernVM-FS](https://cernvm.cern.ch/fs). This requires **admin privileges**, since you need to install CernVM-FS as an OS package. diff --git a/docs/overview.md b/docs/overview.md index bb75c783d..d1212c152 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -34,7 +34,7 @@ The EESSI project consists of 3 layers. ![EESSI overview](img/overview_layers.png) -The bottom layer is the [**filesystem layer**](filesystem_layer), +The bottom layer is the [**filesystem layer**](filesystem_layer.md), which is responsible for distributing the software stack across clients. The middle layer is a [**compatibility layer**](compatibility_layer.md), diff --git a/docs/test-suite/index.md b/docs/test-suite/index.md index be67c25d8..2d7f1ca80 100644 --- a/docs/test-suite/index.md +++ b/docs/test-suite/index.md @@ -2,7 +2,7 @@ The [EESSI test suite](https://github.com/EESSI/test-suite) is a collection of tests that are run using [ReFrame](https://reframe-hpc.readthedocs.io/). -It is used to check whether the software installations included in the [EESSI software layer](../software_layer) +It is used to check whether the software installations included in the [EESSI software layer](../software_layer.md) are working and performing as expected. To get started, you should look into the [installation and configuration guidelines](installation-configuration.md) first. diff --git a/docs/using_eessi/eessi_demos.md b/docs/using_eessi/eessi_demos.md index d9cc7e4b4..598480940 100644 --- a/docs/using_eessi/eessi_demos.md +++ b/docs/using_eessi/eessi_demos.md @@ -36,7 +36,7 @@ even with limited resources only. Let's try running the GROMACS example. -First, we need to make sure that [our environment is set up to use EESSI](../setting_up_environment): +First, we need to make sure that [our environment is set up to use EESSI](setting_up_environment.md): ``` { .bash .copy } source /cvmfs/pilot.eessi-hpc.org/latest/init/bash