- marked as enhancement
[JOSS review] Installation instruction
In a nutshell
Generally speaking, only the comment number 4 is a required modification for the JOSS review. Others are my suggestions.
1. The use of git@bitbucket.org:ocellarisproject/ocellaris.git
in the git clone
command
Using the SSH protocol to access the repo requires extra environment settings from users. I think it may not be a good idea to assume all users have Bitbucket account and have already set up SSH access. I'll suggest using https://bitbucket.org/ocellarisproject/ocellaris.git
in the installation instruction.
2. Building a Singularity image locally requires root
privilege
Building a Singularity image from scratch (i.e., from a Singularity file) requires root
privilege. The instruction, however, does not mention this. I suggest following the common practice in the Linux community: specifying the privilege required for each shell command with a prefix like $
(regular user) or #
(root).
Except building an image from scratch, other Singularity operations do not require root
privilege. This includes pull
and run
. So I'll suggest you upload the Singularity image to some public registries like SingularityHub or Singularity Library and ask users to just pull
and run
the image. In this way, they won't have to deal with the privilege issue.
If uploading a Singularity image to a registry is not an option, then I'll suggest improving the instruction. For example, maybe detailing how to build an image on a machine that users have root
privilege and transfer the image file to HPC systems. Or maybe mention that there are some online Singularity builders, and users without root
privilege can utilize those online services.
3. The purpose of Docker image
It looks like the main purpose of the Docker image is for the CI tests only and is not ready for end-users. If this is true, then I think it does not have to be mentioned in the section of Installation using containers. I believe this will confuse readers. Instead, I think it's better to describe this Docker image in another new section explaining how Ocellaris utilizes the CI tests. Or maybe describing the Docker image in the section Installation using pip for those who want to use pip installation but don't want to deal with dependencies.
4. A clearly-stated list of dependencies
This is required by the JOSS review checklist. As it describes:
Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
So even though the main installation method is through Singularity image, it's better to have a list describing each dependency and its version.
5. The use of pip3
in the section of Installation using pip
pip3
is not general to all use cases, especially for operating systems or environments that have only Python 3. For those systems or environments, they simply use pip
to manage Python 3 packages because they don't have to distinguish between Python 2 and Python 3.
An example: when a user installs FEniCS through Anaconda following FEniCS's official instruction:
$ conda create -n fenicsproject -c conda-forge fenics
$ source activate fenicsproject
$ git clone https://bitbucket.org/ocellarisproject/ocellaris.git
$ cd ocellaris
$ pip3 install .
The user's shell will either find no pip3
or find the wrong pip3
(i.e., the system-wide one). For this example use case, only pip install .
works.
By using pip3
, you are assuming users use some specific systems/environments (for example, Ubuntu, or a fat Anaconda environment), which may not be true. I'm not saying using pip3
in the installation instruction is incorrect, what I'm saying is it will be nice to explicitly describe under what systems/environments the commands are guaranteed to be executed. So when users fail to execute a command, like pip3
, they will know it's because they do not use the same system or environment setup as you do.
Comments (9)
-
reporter -
reporter - edited description
-
reporter - edited description
-
reporter - edited description
-
reporter - edited description
-
reporter - edited description
-
Thanks for testing!
- Git URL changed to https://...
- Added "sudo ..." and uploaded the image to the Library. I have previously used SingularityHub, but stopped since they did not support Singularity 3.0. The new Sylabs Cloud Library worked perfectly, thanks for the hint!
- I split the Docker and Singularity info into separate sections and made it clear the Singularity is the recommended way (but Docker will also work for people who prefer that)
- Added list of dependencies, https://www.ocellaris.org/user_guide/install.html#id1
5) Changed to
python3 -m pip ...
to avoid this confusion.
Thanks for all your helpful comments!
-
reporter Looks good!
-
- changed status to resolved
Documentation updated
- Log in to comment