sending to cran

[sckott]

What are things that need to be done or fixed, etc. before going to cran knowing what we know about the pain that is cran:

Tests

• Ignore all tests on cran except a very few trivial tests
  • Alternatively we could change tests so that we use mocks. I don't think we should spend time on this approach b/c it's much better for the health of the package to have more realistic tests against localstack/minio - tools that keep up with mirroring AWS services, whereas mocks will get out of date and we'd end up with tests that don't reflect current AWS reality

Examples

Currently using a mix of @examplesIf interactive() and @examples \dontrun{ for examples ...

• Make sure examples are NOT run during normal check; right now using examplesIf or dontrun, but we could try an approach like googledrive uses where it uses @examplesIf drive_has_token() - whereas we'd use a fxn like aws_has_creds().
  • I think we should use combination of two things, so: @examplesIf interactive() && aws_has_token() where aws_has_token checks if there is an access key, secret key, and region set. This means examples would only be checked locally in an interactive R session and with those secrets set.
• Where possible. allow examples to run - possible being safe to run, no chance of hitting AWS itself. Probably just util fxns
  • "For the initial CRAN submission of your package, all functions must have at least one example and the example code can’t all be wrapped inside \dontrun{}"

Ideally though (insert SNL gif here) we'd actually allow examples to run more easily, BUT we'd need a way to have some kind of mock AWS account that could be freely hammered with requests, and I don't think that exists

Unfortunately there's no good way of even knowing what credentials the user has, see #71

Vignettes/README

• Use pre-rendered vignettes. Already in place.

Other

There's sure to be other things that will come up later - this section covers all of those 😄

Dependencies

• webmockr v2 https://github.com/ropensci/webmockr/milestone/20 needs to be on cran before this cran submission can happen ‼️

[sckott]

@seankross Curious what you think about examples in this package. One approach is to do e.g.,

#' Are there valid AWS credentials on hand?
#'
#' @export
aws_has_creds <- function() {
  res <- tryCatch(
    paws.common::locate_credentials(),
    error = \(e) e
  )
  !inherits(res, "error")
}

#' Some exported function
#' @export
#' @examplesIf aws_has_creds()
#' run examples ...

BUT - do we think it's a good or at least okay idea to have users that run examples run them against their AWS account? Jenny does this for googledrive as an example, but I wonder if that's a bad idea to pollute their aws account. If we think it's okay, we'd have to be cautious and thoughtful about the examples we use.

thoughts?

[seankross]

do we think it's a good or at least okay idea to have users that run examples run them against their AWS account?

I think we should have complete examples that do not get run. Also something we need to think about in terms of "pollution" and writing examples is that anything we do in sixtyfour should be able to be undone in sixtyfour. Does that answer your question?

[sckott]

For examples that interact with AWS, we'll run examples if:

• interactive() &&
• aws_has_creds() &&
• prompt that asks for confirmation

[sckott]

@seankross working on this and I don't think a prompt makes sense given the way *I think* people use examples in docs. if most people do what I do, I just copy paste code from examples and run what I want to run, not necessarily the whole thing given by the maintainer in the man page. I don't think it's a reasonable assumption that users will make sure they run a function that we make at the top of an example block that uses a prompt, but maybe I'm wrong? Maybe instead of a prompt we can have a little roxygen template we can insert into most/all exported fxn docs that's a warning about potential for polluting their account. thoughts?

[seankross]

I don't think a prompt makes sense given the way I think people use examples in docs...

I agree with you.

Maybe instead of a prompt we can have a little roxygen template we can insert into most/all exported fxn docs that's a warning about potential for polluting their account.

If this is not a heavy lift, let's do this instead.

[sckott]

If this is not a heavy lift, let's do this instead.

shouldn't be, can do