psych-ds/pds-2020-validator-prototype

Provide R package beta-release w/ better installation instructions

Closed this issue · 16 comments

pederisager commented

Hi dev team,

I am trying to download the R version of the validator but keep running into various issues and I can't understand from the download description whether I am just following the instructions incorrectly or if something is wrong with my local R settings.

Could you revise your guidelines for how to install the validator in R to include a click-by-click instruction for install for R package noobs like myself? :)

FelixHenninger commented

Hi Peder, thanks, I feel you!

I think the main issue (or one of them, at least) is that we haven't made a release yet (still incorporating all of your feedback!), and thus there isn't yet an R package file in the releases (actually, what GitHub is listing on the release page are unrelated tags that aren't useful to end users).

If you have a moment, could you download this attached package file (psychds_0.1.0.tar.gz), and, pretending for a moment that you got it from the release page, test whether the remaining instructions in the readme help? If they don't, could you sketch briefly at which point they're getting you stuck?

Thanks a bunch, and sorry for the continued trouble!

-Felix

pederisager commented

Downloaded the file and followed post-download instructions. I had to manually install a couple of dependencies but after that it worked like a charm!

So the problem is essentially that there is no file to be downloaded in the first step of the current guidelines?

FelixHenninger commented

Hej Peder, I'm super-glad to hear that things worked out with the package file -- I didn't know that you had to install the package dependencies manually (I just had them installed already for development), thanks for figuring that out! 👍

So the problem is essentially that there is no file to be downloaded in the first step of the current guidelines?

You tell me! 😉 I think you're in a much better position to evaluate the installation instructions. For sure, the file is missing for the first step, and we don't mention the dependencies, but apart from that, did they make sense to you? Suggestions and feedback are, as always, very welcome!

Kind regards,

-Felix

pederisager commented

Once I had the correct file downloaded everything related to the install was pretty clear. People less familiar with R might be confused about package dependencies that do not automatically download.

The first step in the description however is unclear to me. I did not understand what file it was referring too, and my early mistakes were caused by downloading some other tar file in the "latest release" link. I am used to interacting with R packages on github through devtools::install_github() and very rarely download programs/packages from Github directly. If this is the only viable solution available at the moment, I would prefer the documentation to contain the explicit link to the file, or something like a "click here to download" button.

mekline commented
FelixHenninger commented

Once I had the correct file downloaded everything related to the install was pretty clear. People less familiar with R might be confused about package dependencies that do not automatically download.

I see you! This is going to be fixed automagically once we land on CRAN, so the current installation instructions are a stop-gap until then. In the meantime, I totally see the need for better information.

+1 for devtools::install_github()

We can't, sadly, use install_github() because of the JavaScript validator core, which needs to be put together and inserted in the package separately. Because this compilation process has dependencies outside of R, we can't depend on users building the package locally.
However, install_local() and install_url() from devtools should work given that we provide a package file like the one attached above.

  • @pederisager, would you like to investigate whether either of the two functions solve the dependency issues, starting from a blank R installation? If so, could you take a shot at updating the documentation in the readme? I'd be thrilled to walk you through the commit process if you like.
  • @mekline, what's missing here is a formal release. Would you be comfortable with cutting a 0.2.0 release from what we have, via GitHub's release mechanism? (or 0.2.0-beta1 or something like that?) If so, would you be comfortable with submitting it to CRAN at this point? (we would probably need to drop the beta for that, and someone would need to write a vignette)
pederisager commented

I'd be happy to test this solution and update the readme if necessary. It will probably take me a few days to get around to it though. Will keep you updated on my progress.

  • 👍1
  • ❤️1
FelixHenninger commented

Awesome, thanks so much @pederisager, and no stress -- please let me know if there's anything I can do to help, I'd be glad to!

mekline commented
pederisager commented

I gave updating the readme.md a shot and just submitted a pull request. devtools::install_url() works like a charm and installs dependencies automatically. However, I discovered a separate bug during testing. It appears dplyr is a dependency for the psychds package but is not listed as such. Will create a separate issue for this.

FelixHenninger commented

Hej @pederisager , thanks once more for your feedback!

devtools::install_url() works like a charm and installs dependencies automatically.

That's really funny, because it really shouldn't 😉. The JavaScript validator core should be missing from an installation via devtools, and because it needs to be built and packaged separately, it can't be pulled directly from the repository -- that's why I'm itching to make a library package I can upload to the release page.

Could you possibly re-check, perhaps on a machine that hasn't had the R package installed previously? There might be left-over files that somehow work (I seem to remember that we got you a working installation with a tar.gz package, or was that someone else?). Also, if the missing file causes validation to go through without error messages, that would be something worth testing (and fixing) quickly (missing the validator core raises an error for me, but that might not be the case on every machine).

Thanks a bunch! -F

FelixHenninger commented

I discovered a separate bug during testing. It appears dplyr is a dependency for the psychds package but is not listed as such. Will create a separate issue for this.

Thanks again for this, that was an excellent and eagle-eyed find 😄. Fixed and closed over in #13

FelixHenninger commented

Ok y'all, since this seems like a persistent issue, I've now put together an alpha release which (hopefully) included enough warnings to scare casual would-be-users away.

@pederisager , could you check (and possibly revise) your readme revision pull request in light of how this now looks? I hope this is a better foundation to write documentation on 🙂.

Kind regards, -Felix

FelixHenninger commented

I think this is now pretty much done with thanks to @pederisager clarifications in the readme. 😍 . Peder, or @mekline, would you close this issue if you agree? If nothing happens, and nobody protests, I will close it next weekend.

mekline commented

Thank you! Closing

FelixHenninger commented

All credit here belongs to @pederisager . 🎉 Thank you both! 🙇

  • ❤️1