3  Help

This chapter explains how to ask for help. Questions can range from detailed troubleshooting to general advice. To ensure a positive outcome, please read the entire page before reaching out. Thank you for respecting the time and effort it takes to provide one-on-one support.

Summary

Before you post a question, please work through the steps explained in this chapter.

  • Follow the code of conduct.
  • Do not post sensitive or confidential information.
  • Search existing posts.
  • Update your R packages.
  • If troubleshooting:
    • Attribute the error.
    • Write a reprex.

3.1 Before you post

3.1.1 Code of conduct

All developers, users, and other discussants must follow the code of conduct. Please read it before engaging in dialogue.

3.1.2 Sensitive information

The discussion forums from Section 3.3 are open to the public, and anyone with an internet connection can read them. Please do not share any company confidential information, personally identifiable information, private research data, or any other sensitive information.

3.1.3 Search existing posts

Please check if your question already has an answer. Section 3.3 links to searchable online discussion forums with thousands of existing posts. If a relevant thread already exists, please read it first. Then if necessary, please comment there instead of starting a new post.

3.1.4 Try troubleshooting

For specific errors or other issues, please read this chapter’s section on troubleshooting. Please try to work through the steps yourself before posting a question.

3.2 Troubleshooting

It is okay to reach out if you are struggling to solve a specific problem in a specific project: an error message, a part of the code you are not sure how to write, or any experience with targets that is incorrect, unwelcome, unexpected, or confusing. However, please follow the guidelines below and take an active role in the troubleshooting process.

3.2.1 Update your R packages

If the error is a bug in targets or tarchetypes, it is possible the bug has already been fixed in a newer version. Before posting, please try again with the latest CRAN release of targets (or tarchetypes), then again with the GitHub development version if needed. Please see https://docs.ropensci.org/targets/#installation for installation instructions.

3.2.2 Attribute the error

The targets package itself is independent of most problems that arise in targets pipelines. Most issues come from the user-defined R code, R commands, and R functions that the pipeline calls, as well as other R packages on your system. It is often easiest to diagnose these problems by removing your code from the pipeline and running it without using targets at all. So before you post a question, please attempt to troubleshoot and figure out if targets is truly relevant to the source of the trouble, using the tips in the debugging chapter as needed. If it turns out to be a non-targets issue, then please ask your question in a non-targets forum and write the question accordingly.

3.2.3 Set expectations

Computer code is extremely strict. In order to run properly, it needs to be exactly correct, down to the last detail. That makes every single piece of every single computer program susceptible to programming errors and usage errors. For every bug you discover, there are hundreds of strange and unguessable potential causes. The culprit could be a typo buried deep in the targets codebase, an incorrect hidden assumption lost in translation about how to use targets, an obscure bug in an obscure R package dependency, a mistake in one of your R functions, or some other mysterious or unexpected reason. In addition, you may be the first user to experience the problem. So when you ask for help, it is not enough to state the error and ask what might be the solution. The true answer is too surprising to predict, even for the most experienced experts of R and targets.

3.2.4 Write a reprex

To receive useful feedback, please provide the complete context of the problem, including a reprex. The purpose of a reprex, or reproducible example1, is to eliminate the knowledge gaps, misunderstandings, and hidden assumptions where bugs hide. A reprex is a sample of complete, self-contained, runnable code that fully emulates and reproduces the problem. The code should look clean and readable, be as short and concise as possible, run in as few seconds as possible, and contain only the details most relevant to troubleshooting. You can embed the code inline in your question, or you can upload it to a public repository and post the link. Regardless, please expect that anyone trying to help will read all the code and run the enclosed _targets.R file on their own private computer. This process is hands-on and empirical, so please make it as quick and easy as possible for the people who volunteer their valuable time and energy to answer questions.

The following posts explain how to write a good reprex.

The discussion forums of targets and tarchetypes have excellent reprexes from users.

3.3 Contact

There are many ways to reach out.

3.3.1 Community

You can reach out to the R community at these public forums.

3.3.2 Maintainer

To contact the maintainer directly, please post to the relevant public GitHub Discussions page of the package.2 Examples:

GitHub makes it easy to search for and link to public discussions. Not only does this help users solve their own problems, it also helps the maintainer avoid repetition. So please use discussions instead of private emails, instant messages, or mentions on social media.

3.3.2.1 Out of office

When the maintainer is out of office, the GitHub repositories above will enter vacation mode. During these times, Github interactions are temporarily limited, which means users cannot open or comment on issues or discussions. Each repository has an issue like this one to show when vacation mode is turned on and when the maintainer will return and re-enable interactions.3

  1. Also known as a minimal reproducible example or minimal working example.↩︎

  2. You will need to create a free GitHub account, which is a straightforward process.↩︎

  3. I automate these interaction settings and issues using R functions vacation_on() and vacation_off() from https://github.com/wlandau/dotfiles/blob/main/github/vacation.R.↩︎