Open sstevens2 opened 1 year ago
Thanks for submitting this lesson to The Carpentries Lab, @sstevens2, @dme26, @jcohen02, @ChristinaLK, and @aturner-epcc.
I'll be acting as Editor on this submission, and I aim to work through the Editor checklist before the end of next week. You can expect further posts to this thread after I have finished that but, given the proximity of the northern hemisphere winter holidays, a search for reviewers will need to wait for the new year.
For now, to ensure that the review process runs as smoothly as possible, please make sure you are subscribed to receive notifications from this thread. On the right sidebar of this page you should see a section headed Notifications, with a Customize link. You can click on that and make sure that you have the Subscribed option selected, to receive all notifications from the thread.
You can add a badge to display the status of the review in the README of your lesson repository with the following Markdown:
[![The Carpentries Lab Review Status](http://badges.carpentries-lab.org/15_status.svg)](https://github.com/carpentries-lab/reviews/issues/15)
Note for Reviewers: that there are no figures in the main body of the lesson, but there are a few screenshots in the Using Docker with Github Actions extra episode.
The Introduction and Introducing the Docker Command Line ("Docker command line" section) episodes, and the Container Orchestration and Creating Containers on the Cloud extras use third-level headings for sections (heading lines beginning with ###
). Please adjust these to second level headings.
The Using Docker with Github Actions extra episode contains several top-level headings (heading lines beginning with a single #
) for sections within the page. Please adjust all of the heading levels in this extra episode down one level, #
to ##
, ##
to ###
, etc.
Note for Reviewers: the Instructor Notes extra contains several learner profiles and a further discussion of the potential audiences for the lesson.
The lesson repository includes:
The repository does contain a CC-BY license, but the copyright statement inside should be updated to remove mentions of The Carpentries lesson programs. I suggest replacing it with:
... your work is derived from work that is Copyright © [authors' names] and, where practical, linking to https://carpentries-incubator.github.io/docker-introduction/), ...
and
... the example programs and other software provided in the lesson are made available under the ...
The lesson includes:
Please add key terms to the glossary in the Reference extra. You can include terms and their definitions, or list only terms and link from these to their respective definitions in Glosario.
email
in the _config.yml
file) to point to someone who people can contact about the curriculum.@sstevens2, @dme26, @jcohen02, @ChristinaLK, and @aturner-epcc I have completed the editorial checks and identified only a few points I would like you to address, which you can find in the checklist response above.
Please take some time to work through and address these. You may find it helpful to open an issue for each point on the lesson repository, to help you keep track.
Please post back here after you have addressed my comments. You do not have to respond with an itemised list of all the changes you made - it is sufficient to let me know when you are ready for me to run through the checklist again before I look to assign reviewers for the lesson.
If you have any questions or concerns about any of the points I raised, please post back here. I'd be happy to answer questions and provide more details as you require.
Note that I will be on leave for the next few weeks. I will pick this thread back up when I return.
Many thanks for running through the editorial checks and providing comments @tobyhodges. We'll work through and address these comments and let you know when this has been completed. Have a good break.
For future reference, the following issues have been opened to address the above comments:
To my knowledge, we've closed all the issues @jcohen02 made to address issues @tobyhodges brought up with items missing from the checklist. Next steps?
Great, thank you for the update @sstevens2. I've run through the editorial checklist again and agree that everything is looking good and the lesson is ready for review.
The next step is for me to begin looking for reviewers - a task that I will begin tomorrow.
Thanks everyone for your patience. After some delay, I am delighted to invite @flor14 and @nanjalaruth to review this lesson. Florencia & Ruth, please can you post here to confirm that you are happy to review this lesson?
You can read more about the lesson review process in our Reviewer Guide.
I am ready to review @tobyhodges ! :)
Dear Toby,
I am happy to review!
Regards, Ruth.
On Mon, Sep 18, 2023 at 11:31 AM Toby Hodges @.***> wrote:
Thanks everyone for your patience. After some delay, I am delighted to invite @flor14 https://github.com/flor14 and @nanjalaruth https://github.com/nanjalaruth to review this lesson. Florencia & Ruth, please can you post here to confirm that you are happy to review this lesson?
You can read more about the lesson review process in our Reviewer Guide https://github.com/carpentries-lab/reviews/blob/main/docs/reviewer_guide.md .
— Reply to this email directly, view it on GitHub https://github.com/carpentries-lab/reviews/issues/15#issuecomment-1723142997, or unsubscribe https://github.com/notifications/unsubscribe-auth/ANGRBX3RHMO7ZSLBHX2Y7MDX3APH3ANCNFSM6AAAAAASYVRG5Y . You are receiving this because you were mentioned.Message ID: @.***>
Excellent, thank you both. When you are ready, please post your reviews as replies in this thread. If you have any questions for me during the review, please ask.
Dear All,
I have gone through the lesson and reviewed it based on the checklist. I have also added a few minor comments to the document. See attached.
[x] Learning objectives for the lesson and its episodes are clear, descriptive, and measurable. They focus on the skills being taught and not the functions/tools e.g. “filter the rows of a data frame based on the contents of one or more columns,” rather than “use the filter function on a data frame.”
[] The target audience identified for the lesson is specific and realistic.
I am not sure I saw a section highlighting the target audience, has this been mentioned?
I will finish my review by Oct 15th
Hello! Here is my review. There is a lot of work in the lesson and has been easy to follow it. Congratulations to the authors for all your hard work 🎉 I have included comments but please feel free to use them to improve the lesson as you think is better.
Comments
Comments:
Comment:
arm64
processor can bring. Even if things are better now, this could be an issue.
In my opinion experience, there are 3 moments when this could be a problem in this lesson:
amd64
will have to add --platform linux/amd64
to the command. Read here. If you are selecting an image in DockerHub, better to use one that is available for both architectures. This way, it would not be necessary to specify anything as Docker detects which one is necessary for the computer making the request. Last year this was an issue for rocker
images but not for JupyterLab
ones. In general, the popular and well-maintained repositories offer both:
Build multiplatform Docker images to push to DockerHub: I would add it as supplemental material. In the references section of this link, there are listed articles about how to create them link. Final note: this is based on what I read at the end of 2022, there could be more recent updates.
"virtual"
and "pipeline"
. Wouldn't be better to link the glossary for a more exact description of those terms instead of quoting them? Docker container
and Docker image
instead of 'Container Image' for teaching because it seems less confusing for me. For example, the title of Chapter 6 'Creating Your Own Container Images' would be for me 'Creating your own Docker Images'. I know that some people use it your way, so whatever decision you make about this check that is the same in the Glosario. One option could be to read how these terms are referred to in the official documentation.I appreciate that you clarified the old and new syntax, which can be very confusing.
All the analogies you used made the topics quite clear to understand.
Chapter 3: The explanation of the command ls
as well as your description of what means interactive in the context of the lesson is great, and will be useful for the learners.
The video is a really interesting resource. Would you recommend the instructors to start the lesson with it or is it extra material?
You explain very abstract topics. Do you think that any image of a diagram could help the students to learn? In the video suggested at the start, they are bringing some representations that could be re-used again in the lesson.
The exercise time reported for some of the lessons is 0 min, even if you have exercises. This happens at least in chapters 1 and 2.
You explain some abstract topics in this lesson. So you think that any image of a diagram could help the students to learn? In the video suggested at the start, they are bringing some representations that could be re-used again in the lesson.
Chapter 4: Could be a good moment to check if the students recognized the difference between an image and a running container. I would ask directly in an exercise if to avoid memory issues they should delete the container or the image and which command they will use to do so.
Chapter 7: "How can I make more complex container images?" This title isn't very specific. Probably you use the commands you explain there because you have I will propose questions at the level of detail of the examples/commands you explain in the chapter. The same for the title "More fancy Dockerfile options". The title could be slightly more informative.
Workflow/Good practices? In chapter 6 there is a title that says 'Boring but important notes about the installation': I think this section is far more important than what is mentioned in the title. Basically, you are proposing a workflow to develop a Dockerfile.
--rm
and --name
in a previous chapter. Would you suggest using them as part of a Docker use workflow?Reproducibility
What could be added as part of the topics you are covering?
Thank you both very much for your reviews, @nanjalaruth and @flor14.
@sstevens2, @dme26, @jcohen02, @ChristinaLK, and @aturner-epcc: Reviews are now complete, and you can proceed with making changes and responding to the comments and suggestions whenever you are ready. To help you keep track of the improvements you can make based on these reviews, you may find it helpful to convert individual comments from reviewers, or groups of related comments, into issues on the lesson repository.
@nanjalaruth & @flor14: thank you again for volunteering your time to review the lesson. Please stay subscribed to this thread, so that you can check changes made in response to your review, and in case the lesson developers need to discuss any of your comments while they incorporate the feedback.
Many thanks @tobyhodges, and, indeed, many thanks @nanjalaruth and @flor14 for taking the time to review our Docker lesson. As suggested, we'll go through the review comments and feedback, grouping points as necessary, and open issues for the comments which we can then work to address.
Thanks @tobyhodges for facilitating this review! Also many thanks to the reviewers (@nanjalaruth and @flor14) for your thoughtful review! Looking forward to incorporating your suggestions into the lesson!
@jcohen02 Could you take the lead on convening the maintainers to make issues and co-work on them? We might need a couple sessions but could start with an hour to review and make issues?
@jcohen02 I know you have a lot on at the moment - do you want me to do this coordination?
Thanks @aturner-epcc and apologies, this is on my todo list but I got caught up with some other things. If you have the bandwidth available to take this on, that would be much appreciated. Equally, if things are very busy on your end at the moment too, leave it with me.
Lesson Title
Reproducible Computational Environments Using Containers: Introduction to Docker
Lesson Repository URL
https://github.com/carpentries-incubator/docker-introduction
Lesson Website URL
https://carpentries-incubator.github.io/docker-introduction/
Lesson Description
This lesson aims to teach researchers how to use and create containers using Docker. It requires knowledge of navigating the unix shell and using a text editor but otherwise intended for indviduals with no experience using using Docker or containers.
Author Usernames
@dme26 @jcohen02 @ChristinaLK @aturner-epcc @sstevens2
Zenodo DOI
No response
Differences From Existing Lessons
To our knowledge this lesson is not similar to any of the lessons in the Carpentries Lab or Lesson programs.
Confirmation of Lesson Requirements
JOSE Submission Requirements
paper.md
andpaper.bib
files as described in the JOSE submission guide for learning modulesPotential Reviewers
mkuzak colinsuaze gcapes mmalenta