Merge pull request #108 from boegel/contrib_policy

document contribution policy for adding software to EESSI

🎉

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

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),

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

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).

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.
 

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),

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.

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