Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[REVIEW]: BeamBending: a teaching aid for 1-D shear-force and bending-moment diagrams #65

Open
whedon opened this issue Jul 26, 2019 · 26 comments

Comments

@whedon
Copy link
Collaborator

commented Jul 26, 2019

Submitting author: @alfredocarella (Alfredo Carella)
Repository: https://github.com/alfredocarella/simplebendingpractice
Version: v1.0.0
Editor: @moorepants
Reviewer: @desgarcia, @nicoguaro
Archive: Pending

Status

status

Status badge code:

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

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 instructions & questions

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

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

The reviewer guidelines are available here: https://jose.theoj.org/about#reviewer_guidelines. Any questions/concerns please let @moorepants know.

Review checklist for @desgarcia

Conflict of interest

Code of Conduct

General checks

  • Repository: Is the source code for this software available at the repository url?
  • License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
  • Version: Does the release version given match the GitHub release (v1.0.0)?
  • Authorship: Has the submitting author (@alfredocarella) made substantial contributions to the software? Does the full list of paper authors seem appropriate and complete?

Functionality

  • Installation: Does installation proceed as outlined in the documentation? (and documentation is sufficient?)
  • Functionality: Have the functional claims of the software been confirmed?
  • 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

  • A statement of need: Do the authors clearly state the need for this software and who the target audience is?
  • Installation instructions: Is there a clearly stated list of dependencies? (Ideally these should be handled with an automated package management solution.)
  • Example usage: Do the authors include examples of how to use the software?
  • Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
  • Tests: Are there automated tests or manual steps described so that the function of the software can be verified?
  • 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

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

Review checklist for @nicoguaro

Conflict of interest

Code of Conduct

General checks

  • Repository: Is the source code for this software available at the repository url?
  • License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
  • Version: Does the release version given match the GitHub release (v1.0.0)?
  • Authorship: Has the submitting author (@alfredocarella) made substantial contributions to the software? Does the full list of paper authors seem appropriate and complete?

Functionality

  • Installation: Does installation proceed as outlined in the documentation? (and documentation is sufficient?)
  • Functionality: Have the functional claims of the software been confirmed?
  • 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

  • A statement of need: Do the authors clearly state the need for this software and who the target audience is?
  • Installation instructions: Is there a clearly stated list of dependencies? (Ideally these should be handled with an automated package management solution.)
  • Example usage: Do the authors include examples of how to use the software?
  • Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
  • Tests: Are there automated tests or manual steps described so that the function of the software can be verified?
  • 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

  • Authors: Does the paper.md file include a list of authors with their affiliations?
  • A statement of need: Do the authors clearly state the need for this software and who the target audience is?
  • References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?
@whedon

This comment has been minimized.

Copy link
Collaborator Author

commented Jul 26, 2019

Hello human, I'm @whedon, a robot that can help you with some common editorial tasks. @desgarcia, @nicoguaro it looks like you're currently assigned to review this paper 🎉.

⭐️ Important ⭐️

If you haven't already, you should seriously consider unsubscribing from GitHub notifications for this (https://github.com/openjournals/jose-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:

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

watching

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

This comment has been minimized.

Copy link
Collaborator Author

commented Jul 26, 2019

Attempting PDF compilation. Reticulating splines etc...
@whedon

This comment has been minimized.

Copy link
Collaborator Author

commented Jul 26, 2019

@nicoguaro

This comment has been minimized.

Copy link
Collaborator

commented Jul 26, 2019

@moorepants, should the repository include two license files?

@alfredocarella, do you have a DOI for your reference? Also, I would suggest another reference that is not in Norwegian, preferably in English.

@moorepants

This comment has been minimized.

Copy link
Member

commented Jul 26, 2019

@moorepants, should the repository include two license files?

I'm personally fine with a single license for all materials in the repository. Some people license code separately than other content (text, images, etc.). That is fine too.

@alfredocarella

This comment has been minimized.

Copy link

commented Jul 29, 2019

@alfredocarella, do you have a DOI for your reference? Also, I would suggest another reference that is not in Norwegian, preferably in English.

@nicoguaro Sorry about the late answer.
I have unfortunately not found any DOI for Bell's book, but its ISBN (978-82-450-1685-7) is given in the file paper.bib.
As you very well point out, it is probably a good idea to have a reference in English. I have therefore added "Statics and Mechanics of Materials" by F. Beer (ISBN 978-0-07-339816-7). The relevant sections (i.e. where the topic is introduced) are 12.1 and 12.2.

@alfredocarella

This comment has been minimized.

Copy link

commented Jul 29, 2019

@whedon generate pdf

@whedon

This comment has been minimized.

Copy link
Collaborator Author

commented Jul 29, 2019

Attempting PDF compilation. Reticulating splines etc...
@whedon

This comment has been minimized.

Copy link
Collaborator Author

commented Jul 29, 2019

@alfredocarella

This comment has been minimized.

Copy link

commented Jul 29, 2019

@whedon generate pdf

@whedon

This comment has been minimized.

Copy link
Collaborator Author

commented Jul 29, 2019

Attempting PDF compilation. Reticulating splines etc...
@whedon

This comment has been minimized.

Copy link
Collaborator Author

commented Jul 29, 2019

@nicoguaro

This comment has been minimized.

Copy link
Collaborator

commented Jul 29, 2019

@alfredocarella, it seems that the package only supports statically determined beams with (exactly) one pinned and one roller support. Maybe it is a good idea to explicitly mention this in the documentation and in the paper.

It seems a little bit confusing to me to use interchangeably pinned and fixed. Since the support doesn't constrain rotations.

@alfredocarella

This comment has been minimized.

Copy link

commented Jul 31, 2019

@nicoguaro, thanks for two useful comments. I have done the following to address them:

  • The mentioned limitations in package scope (i.e. only statically determined beams with one pinned and one roller support) is now explicitly mentioned in the documentation, class docstrings, paper.md, and README.md.
  • I have also changed all code and documentation references from "fixed support" to "pinned support", in hopes of making it clearer.

@whedon generate pdf

@alfredocarella

This comment has been minimized.

Copy link

commented Jul 31, 2019

@whedon generate pdf

@whedon

This comment has been minimized.

Copy link
Collaborator Author

commented Jul 31, 2019

Attempting PDF compilation. Reticulating splines etc...
@whedon

This comment has been minimized.

Copy link
Collaborator Author

commented Jul 31, 2019

@nicoguaro

This comment has been minimized.

Copy link
Collaborator

commented Jul 31, 2019

@moorepants, I have some questions regarding the "common" practices in JOSE.

  • How specific should the community guidelines be?

  • Is it OK to suggest to use vector (instead of raster) graphics in the documentation? This would make easier to repurpose the lessons, and even let to automate the translation of them.

@nicoguaro

This comment has been minimized.

Copy link
Collaborator

commented Jul 31, 2019

@alfredocarella, I opened issue #1 regarding the tests.

I also have some comments regarding units, that might be important considering that this is educational content:

  • Units should be preceded by a space (see SI Brochure, §5.3.3). This is done sometimes in the package/documentation and sometimes is not.

  • The package assume a non-SI system of units (m, kN, kN·m). I think that a (brief) mention of the units would be useful.

  • Units should be roman in roman type and not italic (see this). This is sometimes taken into account in the package/documentation and sometimes not.

@moorepants

This comment has been minimized.

Copy link
Member

commented Jul 31, 2019

How specific should the community guidelines be?

One way to handle this is to add a CONTRIBUTING file to the repository. It does not need to be elaborate and just needs to address the items in the checklist, even if is says that contributions aren't accepted.

Is it OK to suggest to use vector (instead of raster) graphics in the documentation? This would make easier to repurpose the lessons, and even let to automate the translation of them.

It is fine to suggest this. It will depend on the author's response as to whether it is possible.

@moorepants

This comment has been minimized.

Copy link
Member

commented Aug 3, 2019

@alfredocarella Can you please cite the primary software dependencies in the paper? Additionally, there are examples of existing software with similar capabilities that are not mentioned in your paper. I'd like to see citations to at least some of these and some note of what your work offers that distinguishes it from them.

@moorepants

This comment has been minimized.

Copy link
Member

commented Aug 5, 2019

@desgarcia and @nicoguaro I see pretty solid progress in the checklists above. This is a reminder that we'd like to complete the reviews by this Friday if possible. Let me know if you have any questions or need help in any way. Can each of you respond here with a check in letting me know if you think you'll be able to finish by the end of Friday? Thank you for your time and expertise.

@nicoguaro

This comment has been minimized.

Copy link
Collaborator

commented Aug 5, 2019

@moorepants, if my comments (above and Issue tracker) are addressed I would be able.

@desgarcia

This comment has been minimized.

Copy link
Collaborator

commented Aug 5, 2019

@moorepants I should be able to complete by the end of the week!

@alfredocarella

This comment has been minimized.

Copy link

commented Aug 8, 2019

@nicoguaro @desgarcia @moorepants Thanks for the feedback. I will start addressing all your suggestions as soon as possible.

@moorepants

This comment has been minimized.

Copy link
Member

commented Aug 10, 2019

@nicoguaro and @desgarcia Thank you very much for the timely reviews. I think that everything looks reasonable and that minor revisions are needed for publication. @alfredocarella Please address any issues posted on your repository, issues in this thread (including missing checkboxes in the list above). These are the main things I'm seeing:

  • Adding/improving community contribution guidelines
  • Improving the explanation of units
  • Citing prior art
  • Improving installation and getting started aspects
  • Student feedback (if available)

Feel free to discuss with the reviewers and me anything in as you make your revision. Will an August 23rd date be suitable to finish the revisions by?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
5 participants
You can’t perform that action at this time.