Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
[REVIEW]: The Climate Equity Reference Calculator #1273
Submitting author: @krueschan (Christian Holz)
Status badge code:
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
@mtobis, please carry out your review in this issue by updating the checklist below. If you cannot edit the checklist please:
Review checklist for @mtobis
Conflict of interest
Code of Conduct
referenced this issue
Feb 23, 2019
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:
For a list of things I can do to help you, just type:
I ran the docker image locally via
and pointing my browser to
I think the "installation" question is ambiguous in the present case. The end user is not expected to be able to run the code on their own machine, but only to interact with the system through a web interface. Thus I am treating "installation" as meaning "ability to attain functionality", rather than "ability to replicate the service". I think the latter may present some difficulties.
(My attempt to do "docker run" per Jed's message did not work. A server was instantiated but it did not respond.)
I think it would have been better to make clear that the code is in php in the html directory. I spent some time trying to figure out where in my docker image it was and how to get it out!
Is this the full paper?
I see only a summary and a reference section.
This is a typical length for a JOSS "paper"; it is not meant to duplicate project documentation, which should be sufficiently complete to enable research using the software.
I'm okay with the present state of installation; having reproduced it locally, I think someone who wishes to run/extend the software (e.g., with new data or alternate analysis methods) would be able to get it working. I'm sure the technical issue you experienced with the docker container is resolvable in principle and won't ask you to spend further time on it.
This work is essentially a web wrapper around https://sourceforge.net/p/gdrs/code/HEAD/tree/gdrsclib/
Let me state categorically that this is very important work and it should be available and documented.
I am not sure whether that sourceforge tree is considered part of the review. I gather it is not.
I believe my job here is to validate the suitability of this submission for JOSS, not its importance to the world, so unfortunately I hit some snags.
All but one of these issues are not really consequential for the intended uses of the code. I have checked off everything except "example usage".
I strongly recommend altering the code so that a first time user can see the documentation without plunging into parameter choices, and that the online documentation be extended with use cases and user stories.
Thanks very much for the review, @mtobis. Below are responses/further questions:
Correct, that is the intention.
The current design, where the "equity splash screen" is shown first that shows the most salient parameters and a sub-set of parameters for them was the result of feedback from end-users who felt overwhelmed if presented with the full complement of settings on first loading the calculator. The settings on the splash screen are documented through extensive glossary entries (I hope the links to glossary entries are identifiable as links, e.g. that clicking "Historical Responsibility" brings up a substantial glossary entry explaining the concept as used here?). So even upon first loading the calculator, the user has access to the documentation of the specific parameter choices presented to them at that stage, which feels perhaps sufficient to me - what else would you expect at this stage?
As far as use cases are concerned, we considered the literature that is references in the manuscript (Adow, Ware, & Viita, 2018; CSO Equity Review, 2015, 2016, 2017, 2018; Holz
Happy to provide manual test cases but I have no idea how I would go about doing that. Can you point me to an example repository that does that? Or some other relevant documentation?
The repository has a CONTRIBUTING.md file and the calculator itself has a "Please send feedback" link at the bottom of each page.
Thanks for the suggestion and see my comments above. I am thinking of adding a line of text on top of the "equity splash screen" that points the first time user to a general introduction of our approach, i.e. this page: https://climateequityreference.org/about-the-climate-equity-reference-project-effort-sharing-approach/
PDF failed to compile for issue #1273 with the following error:
% Total % Received % Xferd Average Speed Time Time Time Current
0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0
@krueschan Can you confirm that Sivan Kartha meets the authorship guidelines with respect to this software? https://joss.readthedocs.io/en/latest/submitting.html#authorship (I ask because there are no commits authored by him.)
After confirmation, please archive the software at Zenodo or similar and report the DOI here.
Small editorial fix in the last paragraph:
“In research by the authors and others, most recently in (Adow … ) among other pieces” >> when you use the citation as part of speech in a sentence, you need to use in-text citation; see: https://rmarkdown.rstudio.com/authoring_bibliographies_and_citations.htm#citation_syntax
Also, comma after “e.g.” in parenthetical a bit later.
Here's what you must now do:
Any issues? notify your editorial technical team...
If you would like to include a link to your paper from your README use the following code snippets:
This is how it will look in your documentation:
We need your help!
Journal of Open Source Software 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: