[REVIEW]: A virtual training module for introducing the use of Amazon Web Services

whedon commented 2 years ago

Submitting author: @abhijna (Abhijna Parigi) Repository: https://github.com/nih-cfde/training-and-engagement Version: 2022.07-aws-jose Editor: @willingc Reviewer: @giuliaguidi, @manics Archive: 10.5281/zenodo.6816045

:warning: JOSS reduced service mode :warning:

Due to the challenges of the COVID-19 pandemic, JOSS is currently operating in a "reduced service mode". You can read more about what that means in our blog post.

Status

Status badge code:

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

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

@giuliaguidi & @manics, 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/jose-reviews/invitations

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

✨ Please start on your review when you are able, and be sure to complete your review in the next six weeks, at the very latest ✨

Review checklist for @giuliaguidi

Conflict of interest

[x] As the reviewer I confirm that I have read the JOSE 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 JOSE code of conduct.

General checks

[x] Repository: Is the source for this learning module available at the repository url?
[x] License: Does the repository contain a plain-text LICENSE file with the contents of a standard license? (OSI-approved for code, Creative Commons for content)
[x] Version: 2022.07-aws-jose
[x] Authorship: Has the submitting author (@abhijna) made visible contributions to the module? Does the full list of authors seem appropriate and complete?

Documentation

[x] A statement of need: Do the authors clearly state the need for this module and who the target audience is?
[x] Installation instructions: Is there a clearly stated list of dependencies?
[x] Usage: Does the documentation explain how someone would adopt the module, and include examples of how to use it?
[x] Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the module 2) Report issues or problems with the module 3) Seek support

Pedagogy / Instructional design (Work-in-progress: reviewers, please comment!)

[x] Learning objectives: Does the module make the learning objectives plainly clear? (We don't require explicitly written learning objectives; only that they be evident from content and design.)
[x] Content scope and length: Is the content substantial for learning a given topic? Is the length of the module appropriate?
[x] Pedagogy: Does the module seem easy to follow? Does it observe guidance on cognitive load? (working memory limits of 7 +/- 2 chunks of information)
[x] Content quality: Is the writing of good quality, concise, engaging? Are the code components well crafted? Does the module seem complete?
[x] Instructional design: Is the instructional design deliberate and apparent? For example, exploit worked-example effects; effective multi-media use; low extraneous cognitive load.

JOSE paper

[x] Authors: Does the paper.md file include a list of authors with their affiliations?
[x] A statement of need: Does the paper clearly state the need for this module and who the target audience is?
[x] Description: Does the paper describe the learning materials and sequence?
[x] Does it describe how it has been used in the classroom or other settings, and how someone might adopt it?
[x] Could someone else teach with this module, given the right expertise?
[x] Does the paper tell the "story" of how the authors came to develop it, or what their expertise is?
[x] References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

Review checklist for @manics

Conflict of interest

[x] As the reviewer I confirm that I have read the JOSE 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 JOSE code of conduct.

General checks

[x] Repository: Is the source for this learning module available at the repository url?
[x] License: Does the repository contain a plain-text LICENSE file with the contents of a standard license? (OSI-approved for code, Creative Commons for content)
[x] Version: 2022.07-aws-jose
[x] Authorship: Has the submitting author (@abhijna) made visible contributions to the module? Does the full list of authors seem appropriate and complete?

Documentation

[x] A statement of need: Do the authors clearly state the need for this module and who the target audience is?
[x] Installation instructions: Is there a clearly stated list of dependencies?
[x] Usage: Does the documentation explain how someone would adopt the module, and include examples of how to use it?
[x] Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the module 2) Report issues or problems with the module 3) Seek support

Pedagogy / Instructional design (Work-in-progress: reviewers, please comment!)

[x] Learning objectives: Does the module make the learning objectives plainly clear? (We don't require explicitly written learning objectives; only that they be evident from content and design.)
[x] Content scope and length: Is the content substantial for learning a given topic? Is the length of the module appropriate?
[x] Pedagogy: Does the module seem easy to follow? Does it observe guidance on cognitive load? (working memory limits of 7 +/- 2 chunks of information)
[x] Content quality: Is the writing of good quality, concise, engaging? Are the code components well crafted? Does the module seem complete?
[x] Instructional design: Is the instructional design deliberate and apparent? For example, exploit worked-example effects; effective multi-media use; low extraneous cognitive load.

JOSE paper

[x] Authors: Does the paper.md file include a list of authors with their affiliations?
[x] A statement of need: Does the paper clearly state the need for this module and who the target audience is?
[x] Description: Does the paper describe the learning materials and sequence?
[x] Does it describe how it has been used in the classroom or other settings, and how someone might adopt it?
[x] Could someone else teach with this module, given the right expertise?
[x] Does the paper tell the "story" of how the authors came to develop it, or what their expertise is?
[x] References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

whedon commented 2 years ago

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

:warning: JOSS reduced service mode :warning:

Due to the challenges of the COVID-19 pandemic, JOSS is currently operating in a "reduced service mode". You can read more about what that means in our blog post.

:star: Important :star:

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:

Set yourself as 'Not watching' https://github.com/openjournals/jose-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 2 years ago

PDF failed to compile for issue #167 with the following error:

 Can't find any papers to compile :-(

whedon commented 2 years ago

Software report (experimental):

github.com/AlDanial/cloc v 1.88  T=0.67 s (267.6 files/s, 39150.2 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Markdown                       151           5438              0          11186
CSS                              4            854             71           6424
JavaScript                       4             31             52           1141
HTML                             5             17             14            316
YAML                            11             37             69            198
R                                2             72             51            157
Python                           1             13              5             30
reStructuredText                 1              5              7              3
-------------------------------------------------------------------------------
SUM:                           179           6467            269          19455
-------------------------------------------------------------------------------

Statistical information for the repository '987c67e456a40fa466967878' was
gathered on 2022/03/31.
The following historical commit information, by author, was found:

Author                     Commits    Insertions      Deletions    % of changes
Amanda Charbonneau              10         20107          20108           96.85
Jeremy Walter                   12             8              8            0.04
Marisa Lim                       2            49              1            0.12
Saranya Canchi                   4          1234              0            2.97
abhijna                          1             5              4            0.02

Below are the number of rows from each author that have survived and are still
intact in the current revision:

Author                     Rows      Stability          Age       % in comments
Marisa Lim                   48           98.0          9.8               10.42
Saranya Canchi             1224           99.2          8.4                4.25

labarba commented 2 years ago

@giuliaguidi, @manics — Thank you for agreeing to review for JOSE! This is where the action happens: work your way through the review checklist, feel free to ask questions or post comments here, and also open issues in the submission repository as needed. Godspeed!

Your Editor, @willingc, will take over the shepherding from here.

labarba commented 2 years ago

@whedon generate pdf from branch AWS_Jose_Paper

whedon commented 2 years ago

Attempting PDF compilation from custom branch AWS_Jose_Paper. Reticulating splines etc...

whedon commented 2 years ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

whedon commented 2 years ago

:wave: @manics, please update us on how your review is going (this is an automated reminder).

whedon commented 2 years ago

:wave: @giuliaguidi, please update us on how your review is going (this is an automated reminder).

giuliaguidi commented 2 years ago

I'll complete it by the end of the week.

GG

On Thu, Apr 14, 2022 at 2:11 PM whedon @.***> wrote:

👋 @giuliaguidi https://github.com/giuliaguidi, please update us on how your review is going (this is an automated reminder).

— Reply to this email directly, view it on GitHub https://github.com/openjournals/jose-reviews/issues/167#issuecomment-1099624972, or unsubscribe https://github.com/notifications/unsubscribe-auth/AEAZJ2AIISSM2CEWL3GWMSLVFCCXNANCNFSM5SGWHX2Q . You are receiving this because you were mentioned.Message ID: @.***>

manics commented 2 years ago

I've read the paper, I'm going through the code/course

manics commented 2 years ago

See

[x] https://github.com/nih-cfde/training-and-engagement/issues/531 for my feedback on the source repository

@abhijna In the Learning Objectives section of the current PDF https://raw.githubusercontent.com/openjournals/jose-papers/jose.00167/jose.00167/10.21105.jose.00167.pdf

Is this formatting correct? Is it meant to be a bulletted list?
The online lesson link to https://training.nih-cfde.org/en/latest/Cloud-Platforms/Introduction_to_Amazon_Web_Services/introtoaws1.html is broken, should it be https://training.nih-cfde.org/en/latest/Cloud-Platforms/Introduction_to_Amazon_Web_Services/introtoaws1/ ? More generally do you have a policy of maintaining deep-links long-term?

abhijna commented 2 years ago

Hi @manics, thanks for reviewing this paper!

See

[ ] JOSE review feedback nih-cfde/training-and-engagement#531 for my feedback on the source repository

Have you considered adding a restrictive IAM policy? For instance you could allow just console access, ec2:*, and whatever else is required, along with a region restriction (it's annoying easy to accidentally switch region without realising).

Your concern about misuse risks to the AWS account holder is completely valid. I will add a note to the IAM Wiki about minimizing IAM user privileges for participants.

Do you recommend people use https://training.nih-cfde.org/en/latest/Cloud-Platforms/Introduction_to_Amazon_Web_Services/introtoaws1/ directly, or would you prefer them to build their own site using your materials?

We recommend using our website and lesson materials. However, those who wish to co-opt this module are welcome to build their own lessons or re-use lessons from other sources.

@abhijna In the Learning Objectives section of the current PDF https://raw.githubusercontent.com/openjournals/jose-papers/jose.00167/jose.00167/10.21105.jose.00167.pdf

Is this formatting correct? Is it meant to be a bulletted list?

You are right, the learning objectives section is meant to be a bulleted list. I will fix that on the submission.

The online lesson link to https://training.nih-cfde.org/en/latest/Cloud-Platforms/Introduction_to_Amazon_Web_Services/introtoaws1.html is broken, should it be https://training.nih-cfde.org/en/latest/Cloud-Platforms/Introduction_to_Amazon_Web_Services/introtoaws1/ ? More generally do you have a policy of maintaining deep-links long-term?

Apologies for the broken link. It should be the latter. I will loop in Dr. Titus Brown (senior author on this paper) to address the question of link maintenance.

abhijna commented 2 years ago

@whedon generate pdf from branch AWS_Jose_Paper

whedon commented 2 years ago

Attempting PDF compilation from custom branch AWS_Jose_Paper. Reticulating splines etc...

whedon commented 2 years ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

abhijna commented 2 years ago

Hi @manics,

I've fixed the broken links/render and incorporated all your suggestions. I have also added an optional Step 5b to the IAM set up Wiki on how to add a permissions boundary.

I am unable to @ tag Titus to this thread to comment on link maintenance.

@willingc, what is the next step in the review process?

willingc commented 2 years ago

@editorialbot generate pdf

willingc commented 2 years ago

@editorialbot recommend-accept

arfon commented 2 years ago

@willingc – I think it's still @whedon in here... (@editorialbot is only active on JOSS thus far).

willingc commented 2 years ago

@whedon generate pdf from branch AWS_Jose_Paper

whedon commented 2 years ago

PDF failed to compile for issue #167 with the following error:

 Can't find any papers to compile :-(

willingc commented 2 years ago

@whedon recommend-accept

whedon commented 2 years ago

No archive DOI set. Exiting...

willingc commented 2 years ago

@whedon commands

whedon commented 2 years ago

Here are some things you can ask me to do:

# List all of Whedon's capabilities
@whedon commands

# Assign a GitHub user as the sole reviewer of this submission
@whedon assign @username as reviewer

# Add a GitHub user to the reviewers of this submission
@whedon add @username as reviewer

# Re-invite a reviewer (if they can't update checklists)
@whedon re-invite @username as reviewer

# Remove a GitHub user from the reviewers of this submission
@whedon remove @username as reviewer

# List of editor GitHub usernames
@whedon list editors

# List of reviewers together with programming language preferences and domain expertise
@whedon list reviewers

# Change editorial assignment
@whedon assign @username as editor

# Set the software archive DOI at the top of the issue e.g.
@whedon set 10.0000/zenodo.00000 as archive

# Set the software version at the top of the issue e.g.
@whedon set v1.0.1 as version

# Open the review issue
@whedon start review

EDITORIAL TASKS

# All commands can be run on a non-default branch, to do this pass a custom 
# branch name by following the command with `from branch custom-branch-name`.
# For example:

# Compile the paper
@whedon generate pdf

# Compile the paper from alternative branch
@whedon generate pdf from branch custom-branch-name

# Remind an author or reviewer to return to a review after a
# certain period of time (supported units days and weeks)
@whedon remind @reviewer in 2 weeks

# Ask Whedon to do a dry run of accepting the paper and depositing with Crossref
@whedon recommend-accept

# Ask Whedon to check the references for missing DOIs
@whedon check references

# Ask Whedon to check repository statistics for the submitted software
@whedon check repository

EiC TASKS

# Invite an editor to edit a submission (sending them an email)
@whedon invite @editor as editor

# Reject a paper
@whedon reject

# Withdraw a paper
@whedon withdraw

# Ask Whedon to actually accept the paper and deposit with Crossref
@whedon accept deposit=true

willingc commented 2 years ago

@whedon check references

arfon commented 2 years ago

@whedon generate pdf from branch AWS_Jose_Paper

whedon commented 2 years ago

Attempting PDF compilation from custom branch AWS_Jose_Paper. Reticulating splines etc...

whedon commented 2 years ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

arfon commented 2 years ago

No archive DOI set. Exiting...

@willingc – there needs to be an archive DOI set before you can do the recommend-accept step.

willingc commented 2 years ago

@whedon recommend-accept

whedon commented 2 years ago

No archive DOI set. Exiting...

willingc commented 2 years ago

@arfon How do you set the archive DOI?

arfon commented 2 years ago

@whedon set xxxx as archive

whedon commented 2 years ago

I'm sorry @arfon, I'm afraid I can't do that. That's something only editors are allowed to do.

arfon commented 2 years ago

(Where xxxx is the DOI string)

arfon commented 2 years ago

From the docs above:

# Set the software archive DOI at the top of the issue e.g.
@whedon set 10.0000/zenodo.00000 as archive

willingc commented 2 years ago

@whedon set 10.21105.zenodo.00167 as archive

whedon commented 2 years ago

10.21105.jose.00167 doesn't look like an archive DOI.

willingc commented 2 years ago

@whedon set 10.21105.zenodo.00167 as archive

whedon commented 2 years ago

10.21105.zenodo.00167 doesn't look like an archive DOI.

willingc commented 2 years ago

@arfon :cry:

arfon commented 2 years ago

@willingc – can you link to the record on Zenodo so I can figure out what DOI you're referencing here?

willingc commented 2 years ago

I was referencing what was in the header of the paper.

arfon commented 2 years ago

Ah OK. The authors need to make an archive of their work with Zenodo, figshare or somewhere else. See the docs about this here: https://openjournals.readthedocs.io/en/jose/editing.html#after-acceptance

arfon commented 2 years ago

The DOI you're referencing currently is the JOSE paper DOI which doesn't include an archive of the software and materials.

willingc commented 2 years ago

Hi @abhijna, The next step would be to make an archive of your work. Thanks!

Ah OK. The authors need to make an archive of their work with Zenodo, figshare or somewhere else. See the docs about this here: https://openjournals.readthedocs.io/en/jose/editing.html#after-acceptance

jgorzalski commented 2 years ago

Hi @abhijna 👋 Just checking in to see if @willingc's comment made sense or if you need more support? Thank you!

abhijna commented 2 years ago

Hi @jgorzalski and @willingc, thanks for the information. I'm working on getting a tagged release and uploading the zip on zenodo. Hoping to have this done shortly!

openjournals / jose-reviews