[REVIEW]: TEAM: Tensegrity Engineering Analysis Master

whedon commented 5 years ago

Submitting author: @ramaniitrgoyal92 (Raman Goyal) Repository: https://github.com/ramaniitrgoyal92/Tensegrity_Engineering_Analysis_Master-TEAM- Version: v2.1 Editor: @Kevin-Mattheus-Moerman Reviewer: @apsabelhaus, @vaishnavtv, @ctdegroot Archive: 10.5281/zenodo.3516978

Status

Status badge code:

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

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) by leaving comments 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 instructions & questions

@apsabelhaus & @vaishnavtv & @ctdegroot, please carry out your review in this issue by updating the checklist below. If you cannot edit the checklist please:

Make sure you're logged in to your GitHub account
Be sure to accept the invite at this URL: https://github.com/openjournals/joss-reviews/invitations

The reviewer guidelines are available here: https://joss.readthedocs.io/en/latest/reviewer_guidelines.html. Any questions/concerns please let @Kevin-Mattheus-Moerman know.

✨ Please try and complete your review in the next two weeks ✨

Review checklist for @apsabelhaus

Conflict of interest

[x] As the reviewer I confirm that I have read the JOSS conflict of interest policy and that there are no conflicts of interest for me to review this work.

Code of Conduct

[x] I confirm that I read and will adhere to the JOSS code of conduct.

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 (v2.1)?
[x] Authorship: Has the submitting author (@ramaniitrgoyal92) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

Functionality

[x] Installation: Does installation proceed as outlined in the documentation?
[x] Functionality: Have the functional claims of the software been confirmed?
[x] Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

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

Review checklist for @vaishnavtv

Conflict of interest

[x] As the reviewer I confirm that I have read the JOSS conflict of interest policy and that there are no conflicts of interest for me to review this work.

Code of Conduct

[x] I confirm that I read and will adhere to the JOSS code of conduct.

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 (v2.1)?
[x] Authorship: Has the submitting author (@ramaniitrgoyal92) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

Functionality

[x] Installation: Does installation proceed as outlined in the documentation?
[x] Functionality: Have the functional claims of the software been confirmed?
[x] Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

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

Review checklist for @ctdegroot

Conflict of interest

[x] As the reviewer I confirm that I have read the JOSS conflict of interest policy and that there are no conflicts of interest for me to review this work.

Code of Conduct

[x] I confirm that I read and will adhere to the JOSS code of conduct.

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 (v2.1)?
[x] Authorship: Has the submitting author (@ramaniitrgoyal92) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

Functionality

[x] Installation: Does installation proceed as outlined in the documentation?
[x] Functionality: Have the functional claims of the software been confirmed?
[x] Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

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 commented 5 years ago

Hello human, I'm @whedon, a robot that can help you with some common editorial tasks. @apsabelhaus, @vaishnavtv, @ctdegroot it looks like you're currently assigned to review 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 a reviewer, you're probably currently watching this repository which means for GitHub's default behaviour you will receive notifications (emails) for all reviews 😿

To fix this do the following two things:

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

watching

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

notifications

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

@whedon commands

For example, to regenerate the paper pdf after making changes in the paper's md or bib files, type:

@whedon generate pdf

whedon commented 5 years ago

Attempting PDF compilation. Reticulating splines etc...

whedon commented 5 years ago

:point_right: Check article proof :page_facing_up: :point_left:

Kevin-Mattheus-Moerman commented 5 years ago

@ramaniitrgoyal92, @apsabelhaus, @vaishnavtv, @ctdegroot, apologies for the delay in getting this review started. This is where the review will take place. The reviewers have tick-box sections and instructions at the top of this issue.

Kevin-Mattheus-Moerman commented 5 years ago

@apsabelhaus, @vaishnavtv, @ctdegroot Let me know if you have any questions.

ramaniitrgoyal92 commented 5 years ago

@whedon generate pdf

whedon commented 5 years ago

Attempting PDF compilation. Reticulating splines etc...

whedon commented 5 years ago

:point_right: Check article proof :page_facing_up: :point_left:

ramaniitrgoyal92 commented 5 years ago

@whedon generate pdf

whedon commented 5 years ago

Attempting PDF compilation. Reticulating splines etc...

whedon commented 5 years ago

:point_right: Check article proof :page_facing_up: :point_left:

ramaniitrgoyal92 commented 5 years ago

@Kevin-Mattheus-Moerman @apsabelhaus @ctdegroot We did the suggested changes. Thanks a lot!

ctdegroot commented 5 years ago

@ramaniitrgoyal92 A few things to look at for now before I get into looking at the actual software:

It is stated that the version is 2.1, but there are no tags in the repository to indicate this.
The paper just contains one main section "Summary". I think it would be better if you added a couple of sections to separate the background information from the description of the software.

ramaniitrgoyal92 commented 5 years ago

@whedon generate pdf

whedon commented 5 years ago

Attempting PDF compilation. Reticulating splines etc...

whedon commented 5 years ago

:point_right: Check article proof :page_facing_up: :point_left:

ramaniitrgoyal92 commented 5 years ago

@ctdegroot We did the suggested changes. Thanks a lot!

vaishnavtv commented 5 years ago

@ramaniitrgoyal92

The version number as submitted to JOSS for review is 2.1, but the technical manual document lists it as 1.x. It'd be helpful to tag releases from the Github repository itself, to avoid conflicting information.

Kevin-Mattheus-Moerman commented 5 years ago

@ctdegroot We did the suggested changes. Thanks a lot!

@ctdegroot can you verify the changes made? Thanks

Kevin-Mattheus-Moerman commented 5 years ago

@ramaniitrgoyal92

The version number as submitted to JOSS for review is 2.1, but the technical manual document lists it as 1.x. It'd be helpful to tag releases from the Github repository itself, to avoid conflicting information.

@vaishnavtv you can tick the version box (it will be removed in future review issues) as we fix the version tag on acceptance.

Kevin-Mattheus-Moerman commented 5 years ago

@apsabelhaus are you able to finalize this review soon? Thanks.

ramaniitrgoyal92 commented 5 years ago

@vaishnavtv We did the suggested changes. Thanks a lot!

apsabelhaus commented 5 years ago

@Kevin-Mattheus-Moerman thanks for the reminder. These next few days are packed for me, but I tentatively hope to complete the review by the end of the week. Thanks for everyone's patience.

apsabelhaus commented 5 years ago

@Kevin-Mattheus-Moerman, it looks like @ramaniitrgoyal92 has changed the name of the repository / submission (from TEAM to MOTES.) I've checked the "code available at the url" box, since Github redirects to the new repository, but it seems the original URL is to the "TEAM" name. Is there a way that the authors should be updating the JOSS submission with the new name, etc.? Are there other dependencies based on name that need to be looked at by the reviewers?

apsabelhaus commented 5 years ago

@ramaniitrgoyal92 I went through a second round of review just now and opened some more issues. Generally speaking, it seems like this review is taking a while, and I don't think that's just because it's the summertime. The code and documentation are still difficult to read and understand, contain typos, etc. This review would probably go by faster if y'all took a second look at JOSS' standards and verified how you think you meet them all, maybe by responding in the issues with an explanation. Additionally, like I recommended in a response to an issue, describing your changes specifically is better than "thanks, we fixed it!" since that doesn't tell me what you changed.

Kevin-Mattheus-Moerman commented 5 years ago

Thanks @apsabelhaus ! @ramaniitrgoyal92 can you respond to these issues? Thanks.

ramaniitrgoyal92 commented 5 years ago

I am currently out of country for a conference. I am working on it in between and will try to finish as soon as possible. Sorry for the delay.

ramaniitrgoyal92 commented 5 years ago

Respond_to_JOSS.docx

ramaniitrgoyal92 commented 5 years ago

@Kevin-Mattheus-Moerman @apsabelhaus Please check the attached file containing the response for all the changes made in the repository. Thanks!

vaishnavtv commented 5 years ago

@ramaniitrgoyal92, sorry for the delay in response, but I think the reviewers would appreciate it if you could comment/respond to the questions in the corresponding issues in the repository itself.

ramaniitrgoyal92 commented 5 years ago

@ramaniitrgoyal92, sorry for the delay in response, but I think the reviewers would appreciate it if you could comment/respond to the questions in the corresponding issues in the repository itself.

We have responded to the comments in the corresponding issues of the repository. Thanks!

ramaniitrgoyal92 commented 5 years ago

Respond_to_JOSS.docx

The complete list of updates can be found in the attached word document.

ramaniitrgoyal92 commented 5 years ago

@ctdegroot @apsabelhaus Could you please check our .docx file response and let us know your ideas? Thanks, indeed!

vaishnavtv commented 5 years ago

@Kevin-Mattheus-Moerman, I've completed the review. The authors have addressed all the issues I have raised, and amended the paper to reflect the edits I've suggested. If there's nothing else left to review on my part, I would like to recommend this paper for publication. Kindly let me know if you'd like my assistance with anything else on this submission.

ramaniitrgoyal92 commented 5 years ago

@vaishnavtv Thank you so much for your helpful reviews! @Kevin-Mattheus-Moerman Appreciate your time and efforts!

Kevin-Mattheus-Moerman commented 5 years ago

@apsabelhaus @ctdegroot can you review the changes proposed by @ramaniitrgoyal92 and summarize what points you feel are still remaining? Thanks!

apsabelhaus commented 5 years ago

I'll work on this today. Thanks for everyone's patience.

apsabelhaus commented 5 years ago

@ramaniitrgoyal92, you mentioned that you'd responded to comments in the issues in the repository in response to @vaishnavtv's point, but I still had to sort through the word document for issue #1 since the full responses weren't actually in the Github issues. This review is becoming tiresome, and it would be very much appreciated if the authors were more careful and more thorough in the future when saying what you did then actually doing so.

apsabelhaus commented 5 years ago

Also, @ramaniitrgoyal92 when sending a reminder for me to complete this review, it's more helpful to use mentions in this thread (which send emails through Github) instead of contacting me directly at my personal email address as the authorship team did a week ago. See for example how @Kevin-Mattheus-Moerman did so.

ramaniitrgoyal92 commented 5 years ago

@apsabelhaus Thanks for your comments! I added a note to the #1 issue. (Note: setup.m must be run every time MATLAB opens, before any other file.) Thanks for reminding us and sorry indeed for the inconvenience!

apsabelhaus commented 5 years ago

@Kevin-Mattheus-Moerman I finished up this penultimate round of reviews. The only remaining issue (which may be substantial, I'm unsure) is the licensing where the authors use someone else's code. If you could take over and work with the authors on that, it would be appreciated, since I can't speak to JOSS' policies. Once that's fixed, I would recommend this submission for publication!

ctdegroot commented 5 years ago

@Kevin-Mattheus-Moerman I'm satisfied with the changes made by the authors and think that is suitable for all points on the checklist.

Kevin-Mattheus-Moerman commented 5 years ago

Thanks @ctdegroot for your help here!

Kevin-Mattheus-Moerman commented 5 years ago

Thanks @apsabelhaus. I can take over. However you also have a "Functionality" box unticked here, are there any remaining issues with the functionality?

In relation to the remaining license issue. Can you explain that in more detail? Are dependencies used without referring to the original works and without including the licences? Or are license conditions from the dependencies not met?

apsabelhaus commented 5 years ago

@Kevin-Mattheus-Moerman thanks for catching the box-checking mistake - just switched "functionality" with "license."

Summary of the potential licensing problem: (questions for you in parentheses)

Authors included multiple files from other works and other authors. (Does JOSS approve of including other open-source code in a submission, as long as the original licenses are included, and the code from other sources does not represent a substantial contribution of the submission?)
Those files originally contained neither attribution nor license from the original source, so were presumably submitted as the authors' original work. Aside - does JOSS have an academic dishonesty statement somewhere that could be referenced in the future?
This has been corrected, now the files I identified have both attribution and the original license copied into the comments in the file. The authors have reviewed the rest of the repository and they believe that all other code is their original work.
However, these licenses are different: Apache in the LICENSE file for the authors' code, MIT for the outside code. (Does there need to be some more explanation of which licenses apply where, or is it generally assumed that any license present in an individual file supersedes one in a root directory of a repository?)

That's all! If these answers are "Yes, this is all OK", then I'll have completed the review!

Kevin-Mattheus-Moerman commented 5 years ago

@ramaniitrgoyal92 can you verify that you clearly state all the third party works and dependencies included with your software? Also can you make sure you check the license terms for these? E.g. if you have to include the license you do etc.

@apsabelhaus thanks for the thorough review! And also for raising these points. If works from others are included they need to be labelled as such (attribution) and the license terms and conditions of such works need to be respected/adhered to. The license chosen by the author would apply to their work only, not the third party works in the repositoty. If included dependencies have a different license these need to be included. Good practice is to have separate folders for each differently licensed object. Quite often there are no issues with such licenses. The copy-left licenses are an exception as they might force the repo to also carry that license. I believe there are no issues with regards to having MIT licensed content (provided attribution is given and also the license is included) in an Apache-2 repo.

Kevin-Mattheus-Moerman commented 5 years ago

@apsabelhaus feel free to tick that license box. Thanks again for your help here!!

apsabelhaus commented 5 years ago

@Kevin-Mattheus-Moerman thanks for the information, it's very helpful for future reviews! I checked the last box, and I recommend this submission for publication. Congrats to the authors for writing a nice and useful piece of software!

ramaniitrgoyal92 commented 5 years ago

@ramaniitrgoyal92 can you verify that you clearly state all the third party works and dependencies included with your software? Also can you make sure you check the license terms for these? E.g. if you have to include the license you do etc.

@Kevin-Mattheus-Moerman
We have included all the third-party dependencies used in our software. We have added license and attribution to the used functions. We have also added the following in the readme file present in the Function_Library.

"This file contains all necessary functions of tensegrity dynamics and statics. The ode solver is written by Kelly Kearney: https://github.com/kakearney/ecosystem-pkg/blob/master/odefixed/ode4.m. Their code MIT License (MIT) is included in the functions."

Thank you all for the helpful suggestions!

Kevin-Mattheus-Moerman commented 5 years ago

@whedon generate pdf

openjournals / joss-reviews