Documentation (#12)

* expand README
* add vignette

Author: assignUser

.Rbuildignore

@@ -11,3 +11,5 @@
 ^codemeta\.json$
 ^\.pre-commit-config\.yaml$
 ^inst/action$
+^doc$
+^Meta$

.github/workflows/test-octolog.yaml

@@ -54,7 +54,7 @@ jobs:
           print("I accidentally logged my: secret_gh_token")
           octo_echo_off()
           
-          readLines("DESCRIPTION") %>%
+          readLines("README.md") %>%
             encode_string(join = TRUE) %>%
             octo_set_output("desc")
 
@@ -85,6 +85,7 @@ jobs:
           print(Sys.getenv("MULTI_LINE2"))
           octo_inform("We can use outputs from previous steps in other steps using the step id.")
           octo_inform("Multiline strings will be automatically converted from their escaped form.")
-          cat('${{steps.step1.outputs.desc }}')
+
+          cat('${{steps.step1.outputs.desc}}')
         shell: Rscript {0}
 

.gitignore

@@ -1 +1,4 @@
 docs
+inst/doc
+/doc/
+/Meta/

DESCRIPTION

@@ -1,13 +1,14 @@
 Package: octolog
-Title: Better Github Action Logging
+Title: Better 'Github Action' Logging
 Version: 0.0.0.9000
 Authors@R: 
     person("Jacob", "Wujciak-Jens", , "[email protected]", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0002-7281-3989"))
-Description: Provides an API for Github workflow commands and
-    makes it possible to signal conditions from within R that will create
-    annotations when used within Github Actions but raise normal R
-    conditions when used interactively.
+Description: Provides an API for 'Github' <https://github.com> workflow
+    commands and makes it possible to signal conditions from within R that
+    will create annotations when used within 'Github Actions'
+    <https://github.com/features/actions> but raise normal R conditions
+    when used interactively.
 License: MIT + file LICENSE
 URL: https://github.com/assignUser/octolog,
     https://assignuser.github.io/octolog/
@@ -22,13 +23,16 @@ Imports:
     utils,
     withr
 Suggests: 
+    knitr,
     covr,
     mockery (>= 0.4.2.9000),
-    testthat (>= 3.0.0)
+    testthat (>= 3.0.0),
+    rmarkdown
+Remotes: 
+    r-lib/mockery
 Config/testthat/edition: 3
 Config/testthat/parallel: true
-Remotes:  
-    r-lib/mockery
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.1.2
+VignetteBuilder: knitr

NEWS.md

@@ -0,0 +1,3 @@
+# octolog 0.0.0.9000
+
+* Added a `NEWS.md` file to track changes to the package.

README.Rmd

@@ -1,18 +1,26 @@
 ---
-output: github_document
+output: 
+    github_document: default
 ---
 
 <!-- README.md is generated from README.Rmd. Please edit that file -->
 
 # octolog
 
 <!-- badges: start -->
+[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
 [![R-CMD-check](https://github.com/assignUser/octolog/workflows/R-CMD-check/badge.svg)](https://github.com/assignUser/octolog/actions)
-[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
+[![pkgcheck](https://github.com/assignUser/octolog/actions/workflows/pkgcheck.yaml/badge.svg)](https://github.com/assignUser/octolog/actions/workflows/pkgcheck.yaml)
 [![Codecov test coverage](https://codecov.io/gh/assignUser/octolog/branch/main/graph/badge.svg)](https://app.codecov.io/gh/assignUser/octolog?branch=main)
 <!-- badges: end -->
 
-Octolog makes it easy to create conditions that create annotations in Github Action workflows and use the other [workflow commands](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions) that are available.
+Octolog provides a complete[^1] API for Github [workflow commands](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions) that makes it easy to create powerful Github Actions that create readable logs. 
+
+ and makes it possible to signal conditions from within R that will create annotations when used within Github Actions but raise normal R conditions
+when used interactively.
+![Annotations on files of a PR](man/figures/error.png)
+
+[^1]: The only exception is [`save-state`](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#sending-values-to-the-pre-and-post-actions) which can only be used in JavaScript actions. 
 
 ## Installation
 
@@ -23,19 +31,14 @@ pak::pak("assignUser/octolog")
 devtools::install_github("assignUser/octolog")
 ```
 
-## Example
-
-Octolog provides drop-in replacements for `cli::cli_warn` and friends:
+## What are *Github Actions*?
+[Github Actions](https://github.com/features/actions) is a powerful,free[^2] [CI](https://devguide.ropensci.org/ci.html) service integrated into every repository on Github. You can use actions created by other users (e.g. the very popular [r-lib/actions](https://github.com/r-lib/actions) collection of R related actions) or create your own customized workflow that fits your needs.
 
-```{r example}
-library(octolog)
+[^2]: For public repositories.
 
-Sys.setenv(GITHUB_ACTIONS = "FALSE")
-octo_warn(c("An important warning!", i = "And a tipp how to avoid this warning."))
+## Example
 
-Sys.setenv(GITHUB_ACTIONS = "TRUE")
-octo_warn(c("An important warning!", i = "And a tipp how to avoid this warning."))
-```
+The best way to see how {octolog} works, is in an actual [workflow](https://github.com/assignUser/octolog/actions/workflows/test-octolog.yaml). For more information please see the [website](assignUser.github.io/octolog) and the vignette [LINK ME]().
 
 ## Code of Conduct
 

README.md

@@ -5,17 +5,24 @@
 
 <!-- badges: start -->
 
+[![Project Status: Active – The project has reached a stable, usable
+state and is being actively
+developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
 [![R-CMD-check](https://github.com/assignUser/octolog/workflows/R-CMD-check/badge.svg)](https://github.com/assignUser/octolog/actions)
-[![Lifecycle:
-experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
+[![pkgcheck](https://github.com/assignUser/octolog/actions/workflows/pkgcheck.yaml/badge.svg)](https://github.com/assignUser/octolog/actions/workflows/pkgcheck.yaml)
 [![Codecov test
 coverage](https://codecov.io/gh/assignUser/octolog/branch/main/graph/badge.svg)](https://app.codecov.io/gh/assignUser/octolog?branch=main)
 <!-- badges: end -->
 
-Octolog makes it easy to create conditions that create annotations in
-Github Action workflows and use the other [workflow
+Octolog provides a complete[^1] API for Github [workflow
 commands](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions)
-that are available.
+that makes it easy to create powerful Github Actions that create
+readable logs.
+
+and makes it possible to signal conditions from within R that will
+create annotations when used within Github Actions but raise normal R
+conditions when used interactively. ![Annotations on files of a
+PR](man/figures/error.png)
 
 ## Installation
 
@@ -27,30 +34,32 @@ pak::pak("assignUser/octolog")
 devtools::install_github("assignUser/octolog")
 ```
 
-## Example
-
-Octolog provides drop-in replacements for `cli::cli_warn` and friends:
-
-``` r
-library(octolog)
-
-Sys.setenv(GITHUB_ACTIONS = "FALSE")
-octo_warn(c("An important warning!", i = "And a tipp how to avoid this warning."))
-```
+## What are *Github Actions*?
 
-    ## Warning: An important warning!
-    ## ℹ And a tipp how to avoid this warning.
+[Github Actions](https://github.com/features/actions) is a
+powerful,free[^2] [CI](https://devguide.ropensci.org/ci.html) service
+integrated into every repository on Github. You can use actions created
+by other users (e.g. the very popular
+[r-lib/actions](https://github.com/r-lib/actions) collection of R
+related actions) or create your own customized workflow that fits your
+needs.
 
-``` r
-Sys.setenv(GITHUB_ACTIONS = "TRUE")
-octo_warn(c("An important warning!", i = "And a tipp how to avoid this warning."))
-```
+## Example
 
-    ## ::warning ::An important warning!%0Aℹ And a tipp how to avoid this warning.
+The best way to see how {octolog} works, is in an actual
+[workflow](https://github.com/assignUser/octolog/actions/workflows/test-octolog.yaml).
+For more information please see the
+[website](assignUser.github.io/octolog) and the vignette [LINK ME]().
 
 ## Code of Conduct
 
 Please note that the octolog project is released with a [Contributor
 Code of
 Conduct](https://assignuser.github.io/octolog/CODE_OF_CONDUCT.html). By
 contributing to this project, you agree to abide by its terms.
+
+[^1]: The only exception is
+    [`save-state`](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#sending-values-to-the-pre-and-post-actions)
+    which can only be used in JavaScript actions.
+
+[^2]: For public repositories.

man/figures/README-pressure-1.png

@@ -0,0 +1,2 @@
+*.html
+*.R

man/figures/annotations.png

@@ -0,0 +1,51 @@
+---
+title: "Introduction to octolog"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Introduction to octolog}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+Getting started with octolog is easy, just replace the *{cli}* conditions functions with their octolog counterpart:
+
+* `cli::cli_inform` $\rightarrow$ `octolog::octo_inform`
+* `cli::cli_warn` $\rightarrow$ `octolog::octo_warn`
+* `cli::cli_abort` $\rightarrow$ `octolog::octo_abort`
+
+In an interactive session you will not see a difference, as the calls are passed through to {cli} but if your code throws conditions within a Github Action (detected via the environment variable `GITHUB_ACTIONS = "true"`) the behaviour will change. The conditions will be signaled in a way that will make them stand out in the log, appear in the action summary and create annotations[^1] on affected files. 
+
+![Annotations on files of a PR.](../man/figures/annotations.png)
+
+You can throw *errors* that do not kill the R session when using `octo_abort()` by setting the optional argument `.fail_fast = FALSE`. This can be useful if you want a workflow to fail (e.g. to block a PR) by throwing an error but do not want to stop the R process.
+
+![Annotations in the workflow summary. ](../man/figures/summary.png)
+
+[^1]: Annotations only work on pull requests.
+
+## Workflow commands
+
+In addition to signaling conditions, Github Actions provide a number of [workflow commands](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions) to interact with the runner and following actions steps. Octolog provides a complete API[^2] for the workflow commands, please see the [function reference](https://jacob.wujciak.de/octolog/reference/index.html) and the official documentation for an overview. To see the workflow commands in practice you can check out the [example workflow](https://github.com/assignUser/octolog/actions/workflows/test-octolog.yaml) or the real world use case of the [pkgcheck action](https://github.com/ropensci-review-tools/pkgcheck-action).
+
+[^2]: The only exception is [`save-state`](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#sending-values-to-the-pre-and-post-actions) which can only be used in JavaScript actions. 
+
+## Security
+
+**In doubt always refer to the [official documentation](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions) and [security hardening guide](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions) and test the behaviour to make sure the functions behave as you expect!**
+
+There are commands that can have an impact on the security of your repository if they are not or wrongly used. As their official documentation is a bit lacking in parts this section will add some additional remarks.
+
+### Masking
+
+Masking values directly (`octo_mask_value`) and masking environment variables and their values (`octo_mask_envvar`) differs in unexpected and undocumented ways.
+
+![Difference in masking values and environment variables. ](../man/figures/masking.png)
+
+Values masked with `octo_mask_value` will be replaced with "\*\*\*"" immediately but environment variables will only be masked in the ***next*** `step:` of the action!
+
+### Stopping command parsing
+
+If you have to log untrusted user input (like commit messages, issue titles ...) you can prevent the execution of workflow commands using `octo_stop_commands`.Internally the function creates a token based on cryptographically secure random bytes from {openssl}, this makes it impossible for a third party to guess the token before submitting their changes (e.g. to a PR) to enable the execution of their untrusted commands. This is not intended to protect against other R code. Due to R's metaprogramming capabilities it is not possible to protect the token within the same R session.
+
+***NEVER*** run untrusted code using an action trigger that gives write access to your repository like "pull_request_target". See this article about [*pwn requests*](https://securitylab.github.com/research/github-actions-preventing-pwn-requests/) for more in-depth information.
+