Joss-reviews: [REVIEW]: eLabFTW - a free and open source electronic lab notebook

[whedon]

Submitting author: @NicolasCARPi (Nicolas CARPI)
Repository: https://github.com/elabftw/elabftw
Version: 1.5.7
Editor: @cMadan
Reviewer: @JohnGriffiths
Archive: 10.6084/m9.figshare.4868882

Status

Status badge code:

HTML: <a href="http://joss.theoj.org/papers/c42d93df34a90a8b5dcd6aa36e618c5f"><img src="http://joss.theoj.org/papers/c42d93df34a90a8b5dcd6aa36e618c5f/status.svg"></a>
Markdown: [![status](http://joss.theoj.org/papers/c42d93df34a90a8b5dcd6aa36e618c5f/status.svg)](http://joss.theoj.org/papers/c42d93df34a90a8b5dcd6aa36e618c5f)

Reviewers and authors:

Please avoid lengthy details of difficulties in the review thread. Instead, please create a new issue in the target repository and link to those issues (especially acceptance-blockers) in the review thread below. (For completists: if the target issue tracker is also on GitHub, linking the review thread in the issue or vice versa will create corresponding breadcrumb trails in the link target.)

Reviewer questions

Conflict of interest

• [x] As the reviewer I confirm that there are no conflicts of interest for me to review this work (such as being a major contributor to the software).

General checks

• [x] Repository: Is the source code for this software available at the repository url?
• [x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• [x] Version: Does the release version given match the GitHub release (1.4.0)?
• [x] Authorship: Has the submitting author (@NicolasCARPi) made major contributions to the software?

Functionality

• [x] Installation: Does installation proceed as outlined in the documentation?
• [x] Functionality: Have the functional claims of the software been confirmed?
• [x] Performance: Have any performance claims of the software been confirmed?

Documentation

• [x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• [x] Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• [x] Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• [x] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g. API method documentation)?
• [x] Automated tests: Are there automated tests or manual steps described so that the function of the software can be verified?
• [x] Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Software paper

• [x] Authors: Does the paper.md file include a list of authors with their affiliations?
• [x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• [x] References: Do all archival references that should have a DOI list one (e.g. papers, datasets, software)?

[whedon]

Hello human, I'm @whedon. I'm here to help you with some common editorial tasks for JOSS. @raamana it looks like you're currently assigned as the reviewer for this paper :tada:.

:star: Important :star:

If you haven't already, you should seriously consider unsubscribing from GitHub notifications for this (https://github.com/openjournals/joss-reviews) repository. As as reviewer, you're probably currently watching this repository which means for GitHub's default behaviour you will receive notifications (emails) for all JOSS reviews 😿

To fix this do the following two things:

1. Set yourself as 'Not watching' https://github.com/openjournals/joss-reviews:

1. You may also like to change your default settings for this watching repositories in your GitHub profile here: https://github.com/settings/notifications

For a list of things I can do to help you, just type:

@whedon commands

[cMadan]

@raamana - I think you've reviewed for JOSS before, so you know how this works. Let me know if you have any questions for me, otherwise just check things off as appropriate and make comments to the authors here or as issues in the project's repo as makes sense :).

[raamana]

Hey, @NicolasCARPi, you need to add a plain text LICENSE containing ones of the OSI approved licenses: https://opensource.org/licenses/alphabetical

[raamana]

hey, @cMadan, sure, I will. Looks like it is all self-explanatory.

[raamana]

To authors: I was able to follow all the steps outlined here at https://elabftw.readthedocs.io/en/latest/install-mac.html

and landed into an error at the final step.

See the image here:

[raamana]

The description of the repo could be improved by opening with the 3 questions listed under the GIF and then proceeding with what is currently the first para.

Under the Installation section, authors could summarize the major requirements, write a line or two about the process, rather than simply linking to another site. This helps the user get an overall idea of the level of involvement and effort needed before getting into details.

[NicolasCARPi]

Dear @raamana , thank you for your constructive criticism :).

1. The licence file was removed from the root to be integrated first in a doc/ folder, which was then moved to another repo. I realize now that this repo does not have a plaintext licence file (although it is in the documentation. Let me fix that (it is now done on hypernext branch, I'll merge it to master later, if needed).

2. Indeed since the 1.4.0 release a few days ago, composer needs to be installed to populate the vendor/ directory. I updated the documentation for Mac. Commit here : https://github.com/elabftw/elabdoc/commit/45e5e3e3bd94103b91f37c7c6027c86c36428a5a
   Doc here : https://elabftw.readthedocs.io/en/latest/install-mac.html

3. The 3 questions have been moved as suggested.

A line or two have been added under the installation section to describe better how it works and what it needs. New readme visible here.

Cheers,
~Nico

[raamana]

Hi Nicolas,

The installation instructions for Composer do not work as noted on their website: https://getcomposer.org/download/

Perhaps it may be better package it with your codebase to reduce the burden on the user, if at all it is possible?

[NicolasCARPi]

Hello,

You are on a Mac right ? Try with http://.
See this issue https://github.com/composer/composer/issues/5685.

Also, composer should not be packaged with the software, it isn't a correct deployment strategy to do that. I used to have the vendor directory tracked by git, but I removed it to reduce the size of the repo (because all the dev dependencies were coming with it).

Now you should know that the default and recommended way to install this software is with Docker, and the docker image takes care of everything, to highly "reduce the burden on the user", in your terms :). Installing it on a server is very quick and easy, as you can see on the install page.

eLabFTW is a server software, and should be installed on a server. Because of its flexibility it is also possible to install it on a personnal computer (Mac or Windows), but it is not the philosophy.

This software aims for correct and secure cryptography, and this can rise issues on the Mac OS X platform because of its outdated OpenSSL, PHP, versions and libraries. This is why the recommended operating system is GNU/Linux (and inside a Docker container).

[raamana]

That clarification helps. I tried to follow the instructions as I was led. What this means is that the user at the very first entry point was not led to the recommended way to install it. So I would recommend updating the instructions to install to follow your line of thought (what you recommend and why), and only unveil more progressively advanced options only as needed, and with appropriate advice.

[NicolasCARPi]

Well, there is a WARNING saying exactly that on top of the Mac and Windows install pages. It is also repeated several times that it needs to be installed on a server, in the Readme, on the documentation home page, on the main website. I don't see how I can make it clearer!

[cMadan]

@raamana - are you still able to review this submission?

[raamana]

Thanks for the reminder, Chris. I will try to give it another to run and test the software on my Mac.

As @NicolasCARPi points out, it should be installed on a server, and ideally be tested by a team, neither of which I don't have access to, for this purpose. So wondering what would be an ideal way to proceed from here.

[NicolasCARPi]

@raamana I can set up a server for you if you wish. It only costs a few dollars per month :) Tell me and I'll give you an IP adress so you can follow this tutorial:
https://www.youtube.com/watch?v=K8CbQl7H5WA

[raamana]

Thanks for the offer. However don't you need few people and/or accounts to test the full functionality?

I am quite busy with few major deadlines end of this month. Can this wait until then? Or if another reviewer could be found to assist with this review, that will be great to keep this going.

[NicolasCARPi]

@raamana, feel free to register several users.
@cMadan can you put another reviewer in there ? :)

[cMadan]

@NicolasCARPi - sure, I'll try and recruit another reviewer

[JohnGriffiths]

@cmadan - I am on board and ready to start reviewing. But despite a lot of browsing this repo it's still not clear to me how I am supposed to do this. Sorry. Please advise.

[cMadan]

@JohnGriffiths - For the most part you need to see if the statements above in the first post are true and check things off accordingly. If something isn't the case, or you otherwise have a suggestion, either post a comment to @NicolasCARPi here (or ask me) or make an issue in the project's repository (https://github.com/elabftw/elabftw) and we'll sort things out until the submission meets JOSS' guidelines. The guidelines are explained in a bit more detail here: http://joss.theoj.org/about#reviewer_guidelines.

@raamana - the current JOSS submission system only allows one reviewer to be assigned at a time, so I'm going to change it to @JohnGriffiths. Nonetheless, please feel free to continue to open issues in the project's repository and make comments here.

[cMadan]

@whedon assign @JohnGriffiths as reviewer

[whedon]

OK, the reviewer is @JohnGriffiths

[raamana]

No problem, I would have more time starting next week, whence I can help with others if you need me to.

[cMadan]

@JohnGriffiths - do you have any questions about the process that I might be able to help with?

[cMadan]

@raamana, @JohnGriffiths - are either of you able to review this submission?

[JohnGriffiths]

Trying to but so far haven't been able to install

https://github.com/elabftw/elabftw/issues/349

[cMadan]

@JohnGriffiths - thanks for the update!

[NicolasCARPi]

@JohnGriffiths Now that you have access to your own install, did you manage to progress on the review?

Cheers,
~Nico

[JohnGriffiths]

@cMadan I've been through the cloud instance and the functionality all seems fine. I've updated all the tick boxes above. The only thing I can't give a tick for is installation, since as you know I wasn't able to install successfully on linux.

[NicolasCARPi]

That's really too bad that you didn't manage to install. I'll just leave this here:

[cMadan]

@JohnGriffiths - thanks for your work in reviewing this! I know you spent a good deal of time trying to evaluate it and I really appreciate it

@NicolasCARPi - I am sufficiently satisfied that others have been able to install eLabFTW, and your Github issues are quite active, that I believe that others will be able to set-up the software. If you can provide the DOI to an archive of the current version of the software, I am happy to accept your paper at JOSS.

[NicolasCARPi]

@cMadan Great news :) What do you mean by "provide a DOI to an archive"?

This is a link to the latest version:
https://github.com/elabftw/elabftw/archive/1.5.6.tar.gz

[cMadan]

@NicolasCARPi - Basically, we require that the archive be stored on a service such as Zenodo or figshare, please see the end of the author guidelines section here (http://joss.theoj.org/about#author_guidelines)

[NicolasCARPi]

@cMadan Thanks for the clarification. Here is the DOI: 10.6084/m9.figshare.4868882 :)

[cMadan]

@whedon set 10.6084/m9.figshare.4868882 as archive

[whedon]

OK. 10.6084/m9.figshare.4868882 is the archive.

[cMadan]

@NicolasCARPi - Perfect, thank you!

@arfon - We're all set to accept! :)

[arfon]

@NicolasCARPi - please could you remove the "Links" section as this breaks the paper compilation with pandoc.

# Links

- [Official website](https://www.elabftw.net)
- [Documentation](https://elabftw.readthedocs.io)
- [Live demo](https://demo.elabftw.net)
- [GitHub repository](https://github.com/elabftw/elabftw)

We already link to the GitHub repository in the compiled PDF so this one can be removed and the other links should be cited in the text in the main Summary section (and then the references in a bibtex file). You can see a recent example of how to do this here: https://github.com/ropensci/getCRUCLdata/tree/master/inst/paper

[NicolasCARPi]

@arfon I made the requested changes (see commit above). Cheers. Nico.

[arfon]

@JohnGriffiths many thanks for the review here and @cMadan for editing this one ✨

@NicolasCARPi - your paper is now accepted into JOSS and your DOI is http://dx.doi.org/10.21105/joss.00146 ⚡️ 🚀 💥

[JohnGriffiths]

You're welcome. Well done, good work all.