This vignette describes our recommended workflow for contributing your work to the EpiForsk package, using the usethis package.
There are a few steps you must complete the first time you want to contribute, or when you change computer:
The next steps describe the workflow from starting work on a new contribution to merging into the source repository:
To get your git credentials set up, follow these steps:
Log into github.
go to github and click
on “generate new token”.
Fill out the form. When using
usethis::create_github_token(), the scope has been
Copy the generated token and store it somewhere safe.
gitcreds::gitcreds_set() to register the token
in the local Git credential store.
Remember to regenerate and restore your PAT on the schedule set in step 3. The default period recommended by github is 1 month.
For more details, you can read the usethis vignette git-credentials.
To protect the source repository, you must copy it to your own github account, and then clone it to get a local copy. This is accomplished with
::create_from_github("https://github.com/Laksafoss/EpiForsk", fork = TRUE)usethis
When working on a contribution, do so on a separate feature branch. It is best practice to never make commits to the default branch of a fork. To create your feature branch, run
When you’re done working on your contribution, commit it to your local clone. This can be done using the git tab in R-studio. Remember to stage any file you want to include in your commit and write a descriptive commit message. It is ok to make multiple commits before initiating a pull request. To do this, run
This will open a webpage letting you initiate the PR. take note of the PR number, as this is used to reference the PR.
At this point, a package maintainer will look at your PR, and they
will either accept it or request changes. If changes are requested, work
on resolving the issues. Any changes you make must be committed to your
local branch, then pushed upstream using
usethis::pr_push(). If changes have been committed by the
reviewer, you can pull these using
When all issues are resolved, the PR will be accepted and merged into the source repository. At this point, you should run
This will switch you back to the default branch, pull changes from the source repository and delete the local feature branch.
When preparing a contribution, you should put some thought into the format you use. We imagine most contributions will either be in the form of a vignette or a function.
Think of vignettes as an article, where you can write down thoughts and ideas in a free text format, as well as writing R code. This can be useful for sharing examples/guides on data management, analysis methods, r packages, and so on.
In contrast to vignettes, R functions have much stricter formal requirements. Use R functions when you need to automate a common task, such as a data management task. There are a lot of considerations to writing a good R function, and it will generally be a bigger commitment than writing a vignette. A function needs good documentation, explaining what it does and how to use it. It should also have comprehensive and descriptive error handling. The goal is not to make the sleekest, fastest and most efficient functions, but rather implementing functionalities tailored to our specific needs. With that said, writing functions is not a one and done process, and we encourage you to improve functions added to the package over time.
For a deep dive into writing packages, check out Hadley’s R package book.