[REVIEW]: Org-Coursepack about jose-reviews HOT 63 CLOSED

Thank you so much @labarba for all your help!! And thank you @pschloss and @gregcaporaso for your insightful reviews!

from jose-reviews.

from jose-reviews.

Our lovely bot whedon can change the version 😁

from jose-reviews.

I just updated the repo with improved testing - now it also includes testing of org-coursepack-update-lecture-metadata script as well as updating of class schedule table.

from jose-reviews.

All changes look good, I recommend publication.

from jose-reviews.

Congratulations, @joonro! 🎉

Sincere thanks to @pschloss, @gregcaporaso for their careful reviews 🙏

from jose-reviews.

Hello human, I'm @whedon, a robot that can help you with some common editorial tasks. @pschloss, it looks like you're currently assigned as the reviewer for 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:

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

from jose-reviews.

Attempting PDF compilation. Reticulating splines etc...

from jose-reviews.

👉 Check article proof 📄 👈

from jose-reviews.

@pschloss, @gregcaporaso — Thank you for agreeing to review this submission for JOSE. We're so grateful for your volunteer efforts! This is where the action happens. You will work through the checklist above, and ask questions here as needed. You may also open issues in the submission's repository, and post a link here.

from jose-reviews.

The manuscript describes a tool to be used in the Org mode of emacs to generate a course bundle with a syllabus, handouts, and slides. I like the idea of having a single styling that can be applied across all layers of a course packet. The authors point out that this is often done using various tools such as MS Word and PowerPoint. Another advantage is the ability to use text-based files that could be maintained under version control to track the changes to a course's content over time and foster collaboration.

To be transparent, I've never been successful in using emacs. Whether the package works as described needs to be reviewed by someone else. But, I found it difficult to navigate the documentation and templates. I could see something like this being a motivation to learn emacs and engage in this type of material in the future. Unfortunately, I find accessing the package at this level impenetrable. The installation notes state, "Clone the repo or download the ZIP archive". Again, I don't know much about emacs, but that seems pretty minimalist. Are there commands within emacs that would need to be run to load the package? Where in a directory structure in relation to the templates do I need to be to use the package? How would I build the examples? Descriptions of these steps should probably be in the README. The authors are clear that the package is for people with "basic knowledge of Org mode" and so the package is not for me. I worry that the community of people with this level of knowledge is pretty limited.

If possible, I would encourage the authors to separate the templates from the organization in their repo organization. Although the material is elsewhere, I think the README could use a more expansive description of how the repository is organized.

Example Usage / Functionality documentation. Could the authors perhaps create a video or set of annotated screenshots that shows how to generate one of the example course packets?

Community guidelines. I would encourage the authors to create a CONTRIBUTION.md file in their repository that indicates how the community can engage with the developers to help with further development.

from jose-reviews.

apologies to @gregcaporaso if i accidentally checked/unchecked anything from your checklist!

from jose-reviews.

The authors present Org-Coursepack, a set of tools for deriving lecture materials (slides, handouts, syllabus, exams) using emacs/Org. I'm probably not an ideal reviewer for this work as I've never used Org, and I rarely use emacs. If the other review (@pschloss) is also not an emacs/Org user, than I think it would make sense to consider adding a third reviewer who is more familar with these tools (I avoided reading @pschloss's review while preparing mine).

I have reviewed the example lecture materials and project documentation, and the resulting course materials do seem very nicely organized. I can see how Org-Coursepack use by an instructor would be beneficial to a class.

Version: Does the release version given match the GitHub release (v1.0.1)

The most recent release version on GitHub is 1.1.0 - that doesn't match this version number, but does match a version number.

I created a few specific issues that I think would be important to address before publication:

• joonro/Org-Coursepack#1

• joonro/Org-Coursepack#2

• joonro/Org-Coursepack#3

from jose-reviews.

apologies to @gregcaporaso if i accidentally checked/unchecked anything from your checklist!

No worries! And apologies if I checked/unchecked any of yours (I got lost in that comment block a couple of times and worried that I may have messed with your list).

from jose-reviews.

@pschloss and @gregcaporaso, thank you so much for your valuable comments. We will work to address them and report back.

from jose-reviews.

Dear @pschloss, we just added CONTRIBUTING.md (commit: joonro/Org-Coursepack@51c28d2) to address your comment regarding Community guidelines. Please let me know if you need anything else regarding this issue.

We will add the quickstarter guide with screenshots. We believe that will address your comment regarding Example Usage / Functionality documentation. Thank you very much!

from jose-reviews.

Thanks for adding the CONTRIBUTING.md file. I'm not seeing the quickstarter guide. Given that neither @gregcaporaso nor I have much experience with OrgMode or emacs, it would be ideal if @labarba could find someone to finish the review who does have experience. Perhaps Naupaka Zimmerman (gh: naupaka) or Kara Woo (gh: karawoo) would be up for it?

from jose-reviews.

Yes we are working on the quickstarter guide. I will report back when it is done!

from jose-reviews.

Dear @pschloss and @gregcaporaso,

We have made significant updates to make Org-Coursepack more approachable to a wider audience, even those who are new to OrgMode or Emacs. Please see the updated repo. Specifically, based on your feedback, we focused on the following two things.

First was creating the Quickstart guide. This guide provides step-by-step instructions with screenshots of examples so that users can jumpstart a new course construction.

Second, we substantially improved the installation instructions based on your comments. As a part of this update, we added an example init file for Emacs, which (a) includes basic user settings and (b) automatically installs necessary packages required to use the Org-Coursepack. We apologize for not including these instructions previously.

We realized from your valuable comments the importance of making the Org-Coursepack more approachable to various levels of users, and thus, have made a concerted effort to achieve this. Please let us know if you have any other comments or suggestions. Thank you for your time, and happy holidays!

from jose-reviews.

👋 @pschloss, @gregcaporaso Happy New Year!
When you have a chance, can you go over the improvements to this submission? If you're satisfied, all we need from you is a statement that you recommend publication, here on this thread. (Please check off remaining items on the checklist.) And if you still find some items lacking, let us know.
Thanks!

from jose-reviews.

I recommend publication

from jose-reviews.

@pschloss You have a few unchecked items in the checklist. Are you checking these off with your recommendation now?

from jose-reviews.

@gregcaporaso 👋 — You have a few unchecked items in the review checklist. Are you still working on your review?

from jose-reviews.

Yes, I am - I should be done by the end of this week @labarba .

from jose-reviews.

The new quickstart guide looks great - thanks @joonro!

There are two items in my list that I can't check off yet:

Version: Does the release version given match the GitHub release (v1.0.1)?

The version listed on this page is 1.0.1, but the most recent version of the project is 1.1.0. I suspect this just needs to be updated on this page.

Tests: Are there automated tests or manual steps described so that the function of the software can be verified?

There are not automated tests - this came up in joonro/Org-Coursepack#1. The quickstart guide could be viewed as tests that can be run manually, though that may be too time consuming to reasonably be run every time a PR is issued or merged. Do other Org projects have automated tests associated with them? Matching the testing approach for other Org projects is probably what should be considered sufficient for this project.

from jose-reviews.

Thank you @gregcaporaso. Regarding the version number difference, I don't think I can update the issue. I was wondering if that is something you can modify so it reflects the number on the repo? @labarba, Please let me know if I need to do something to update it.

We will look into incorporating automated tests and report back soon!

from jose-reviews.

@whedon set v1.1.0 as version

from jose-reviews.

OK. v1.1.0 is the version.

from jose-reviews.

Thank you!

from jose-reviews.

Dear @gregcaporaso,

We just finished adding automated tests to the repo using Travis CI as you requested. They include exporting of all course contents (syllabus, lecture, exam, and assignment) from the semester template Org file. In addition, the tests load the example init file before exporting contents and thus the validity of the init file (Emacs package installation and other settings) is automatically checked as well.

Please let me know if you need anything else, and thank you very much.

from jose-reviews.

Both reviewers have recommended publication. Hooray!

from jose-reviews.

@whedon generate pdf

from jose-reviews.

Attempting PDF compilation. Reticulating splines etc...

from jose-reviews.

👉 Check article proof 📄 👈

from jose-reviews.

Absolutely great. Thank you all.

from jose-reviews.

@joonro — I do have one editorial request: that you add a section heading Statement of Need, as described in the Author Guidelines. You can put under that heading the paragraphs in your paper that address the need for Org-Coursepack.

from jose-reviews.

Also, please add a section heading before the References list.

from jose-reviews.

@labarba I just added the two headings and pushed the changes. Thank you very much!

from jose-reviews.

@pschloss and @gregcaporaso, thank you so much -- we really appreciated your feedback!

from jose-reviews.

@whedon generate pdf

from jose-reviews.

Attempting PDF compilation. Reticulating splines etc...

from jose-reviews.

👉 Check article proof 📄 👈

from jose-reviews.

OK, @joonro! Now we'll need you to make an archive on Zenodo (make sure to edit the title and author list there to match the paper), and report the archive DOI here.

from jose-reviews.

@labarba, here is the archive DOI:

v1.2.0 joonro/Org-Coursepack: Journal of Open Source Education Publication
DOI: 10.5281/zenodo.2539667

I had to bump up the version number to v1.2.0 since I already had a release with v1.1.0. May I ask you to update the version number of the submission?

Please let me know if you need anything else, and thank you very much!

from jose-reviews.

@whedon set v1.2.0 as version

from jose-reviews.

OK. v1.2.0 is the version.

from jose-reviews.

@whedon set 10.5281/zenodo.2539667 as archive

from jose-reviews.

OK. 10.5281/zenodo.2539667 is the archive.

from jose-reviews.

@whedon accept

from jose-reviews.

Attempting dry run of processing paper acceptance...

from jose-reviews.

Check final proof 👉 openjournals/jose-papers#22

If the paper PDF and Crossref deposit XML look good in openjournals/jose-papers#22, then you can now move forward with accepting the submission by compiling again with the flag deposit=true e.g.

@whedon accept deposit=true

from jose-reviews.

@whedon accept deposit=true

from jose-reviews.

Doing it live! Attempting automated processing of paper acceptance...

from jose-reviews.

🚨🚨🚨 THIS IS NOT A DRILL, YOU HAVE JUST ACCEPTED A PAPER INTO JOSE! 🚨🚨🚨

Here's what you must now do:

0. Check final PDF and Crossref metadata that was deposited 👉 openjournals/jose-papers#23
1. Wait a couple of minutes to verify that the paper DOI resolves https://doi.org/10.21105/jose.00034
2. If everything looks good, then close this review issue.
3. Party like you just published a paper! 🎉🌈🦄💃👻🤘

Any issues? notify your editorial technical team...

from jose-reviews.

Dear @labarba, I'm so sorry, I just noticed that the second author's first name is missing a hyphen (should be Jae-Eun Namkoong instead of Jae Eun Namkoong). Would it be possible to change this?

from jose-reviews.

Did you fix the paper source?

@arfon — Can you help me? I'm not sure what to do here: the author wants a hot fix on the author name. Can we update the PDF with @whedon generate pdf? Do we have to do something else with the Crossref deposit if the paper is fixed after publication?

from jose-reviews.

Yes I just fixed the paper source. I'm sorry again for the inconveniences!

from jose-reviews.

@arfon — Can you help me? I'm not sure what to do here: the author wants a hot fix on the author name. Can we update the PDF with @whedon generate pdf? Do we have to do something else with the Crossref deposit if the paper is fixed after publication?

Unfortunately Whedon doesn't currently support updates like this. If you still have Whedon installed locally then you'll need to do the download and compile steps locally. I can then update the repos with the latest PDF and update the Crossref metadata.

from jose-reviews.

Thanks, @arfon — I used whedon locally to re-download the submission repository to whedon/tmp, I re-compiled with bundle exec whedon compile 34, copied the files over to the local jose-papers repo in the correct folder, then pushed to the remote (both the PDF and XML files).

Should I now run bundle exec whedon deposit 34 locally, and that will do it?

from jose-reviews.

BTW, I got this warning after the compilation:

[WARNING] Missing character: There is no ― in font [lmroman10-regular]:mapping=tex-text;!
tmp/34/10.21105.jose.00034.pdf

... but the PDF looks OK to me.

from jose-reviews.

Should I now run bundle exec whedon deposit 34

Yes, that should do it.

from jose-reviews.

🎉🎉🎉 Congratulations on your paper acceptance! 🎉🎉🎉

If you would like to include a link to your paper from your README use the following code snippets:

Markdown:
[![DOI](https://jose.theoj.org/papers/10.21105/jose.00034/status.svg)](https://doi.org/10.21105/jose.00034)

HTML:
<a style="border-width:0" href="https://doi.org/10.21105/jose.00034">
  <img src="https://jose.theoj.org/papers/10.21105/jose.00034/status.svg" alt="DOI badge" >
</a>

reStructuredText:
.. image:: https://jose.theoj.org/papers/10.21105/jose.00034/status.svg
   :target: https://doi.org/10.21105/jose.00034

This is how it will look in your documentation:

We need your help!

Journal of Open Source Education is a community-run journal and relies upon volunteer effort. If you'd like to support us please consider doing either one (or both) of the the following:

• Volunteering to review for us sometime in the future. You can add your name to the reviewer list here: http://jose.theoj.org/reviewer-signup.html
• Making a small donation to support our running costs here: https://www.flipcause.com/secure/cause_pdetails/Mjk3ODA=

from jose-reviews.

https://twitter.com/JOSE_TheOJ/status/1085239274902077441

from jose-reviews.