From b1287edc3f12293a6fba39c1df3a480ca06b2e19 Mon Sep 17 00:00:00 2001 From: cicdguy <26552821+cicdguy@users.noreply.github.com> Date: Thu, 22 Feb 2024 06:15:30 -0600 Subject: [PATCH 1/2] chore: Remove trailing whitespaces and add proper highlighting for YAML examples --- README.md | 2 +- content/cicdworkflows-enhanced/_metadata.yaml | 2 +- .../posts/validate/validate.qmd | 16 +-- content/cicdworkflows-minimum/_metadata.yaml | 2 +- .../posts/code-coverage.qmd | 114 ++---------------- .../cicdworkflows-minimum/posts/pkgdown.qmd | 14 +-- .../posts/r-cmd-check/r-cmd-check.qmd | 10 +- .../cicdworkflows-recommend/_metadata.yaml | 2 +- .../posts/check-links/check-links.qmd | 6 +- index.qmd | 36 +++--- post/posts/gh-actions.qmd | 22 ++-- 11 files changed, 69 insertions(+), 157 deletions(-) diff --git a/README.md b/README.md index 20c778a..cedae13 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ - + # PharmaDevOps diff --git a/content/cicdworkflows-enhanced/_metadata.yaml b/content/cicdworkflows-enhanced/_metadata.yaml index 606147a..9a99026 100644 --- a/content/cicdworkflows-enhanced/_metadata.yaml +++ b/content/cicdworkflows-enhanced/_metadata.yaml @@ -1,4 +1,4 @@ comments: - giscus: + giscus: repo: phuse-og/devops category: General diff --git a/content/cicdworkflows-enhanced/posts/validate/validate.qmd b/content/cicdworkflows-enhanced/posts/validate/validate.qmd index d0c8576..8da529e 100644 --- a/content/cicdworkflows-enhanced/posts/validate/validate.qmd +++ b/content/cicdworkflows-enhanced/posts/validate/validate.qmd @@ -1,7 +1,7 @@ --- title: "theValidator" description: | - This workflow will take your documentation, and link it to unit testing, creating a report that links requirements (documentation) to tests of those requirements. + This workflow will take your documentation, and link it to unit testing, creating a report that links requirements (documentation) to tests of those requirements. categories: - Testing - Documentation @@ -21,15 +21,15 @@ toc: true ## Why should I use this? -Validation is not a fixed term, and it is strongly recommended to make yourself aware of the work of the R Validation Hub (https://www.pharmar.org/), including the +Validation is not a fixed term, and it is strongly recommended to make yourself aware of the work of the R Validation Hub (https://www.pharmar.org/), including the regulatory repo project. -When using an R package, it is important to know that what the documentation claims the package does is tested, and these tests pass on the -environment you will be using. This gh-action generates a generic report, that takes the documentation and links it to the -unit tests, and records how the the tests performed against a specific R environment. +When using an R package, it is important to know that what the documentation claims the package does is tested, and these tests pass on the +environment you will be using. This gh-action generates a generic report, that takes the documentation and links it to the +unit tests, and records how the the tests performed against a specific R environment. -The aim here is to who in a pan-company way to document the relationship between documentation and tests. Before -using internally, you would need to 1) confirm the documentation is well written, 2) the unit tests are sufficient to +The aim here is to who in a pan-company way to document the relationship between documentation and tests. Before +using internally, you would need to 1) confirm the documentation is well written, 2) the unit tests are sufficient to test that documentation and 3) you are assessing against the actual environments you use internally. ## How do I set it up? @@ -37,7 +37,7 @@ test that documentation and 3) you are assessing against the actual environments Below is an example of using this `gh-action` when a release is made. -```bash +```yaml --- name: R Package Validation report diff --git a/content/cicdworkflows-minimum/_metadata.yaml b/content/cicdworkflows-minimum/_metadata.yaml index 606147a..9a99026 100644 --- a/content/cicdworkflows-minimum/_metadata.yaml +++ b/content/cicdworkflows-minimum/_metadata.yaml @@ -1,4 +1,4 @@ comments: - giscus: + giscus: repo: phuse-og/devops category: General diff --git a/content/cicdworkflows-minimum/posts/code-coverage.qmd b/content/cicdworkflows-minimum/posts/code-coverage.qmd index 86758e7..e6fb197 100644 --- a/content/cicdworkflows-minimum/posts/code-coverage.qmd +++ b/content/cicdworkflows-minimum/posts/code-coverage.qmd @@ -1,10 +1,11 @@ --- -title: "Code coverage" +title: "Check code coverage" description: | - This workflow checks whether URLs embedded in code and documentation are valid. Invalid URLs result in workflow failures. + This workflow measures code coverage for unit tests and reports the code coverage as a percentage of the total number of lines covered by unit tests vs. the total number of lines in the codebase. categories: - - Documentation - - Links + - Testing + - R +author: Pharmaverse date: 2023-08-01 image: https://covr.r-lib.org/reference/figures/logo.png toc: true @@ -25,21 +26,21 @@ This workflow measures code coverage for unit tests and reports the code coverage as a percentage of the *total number of lines covered by unit tests* vs. the *total number of lines in the codebase* in an R package. -Using this github action gives you a badge that helps to show that the code is coverage. Calculating this +Using this github action gives you a badge that helps to show that the code is coverage. Calculating this via CICD is useful as the amount of untested code can vary, e.g. a new feature is added but it is not tested. People often use this metric as an indicator of code quality and maturity. -It's important to note that code coverage is only telling you if a test exists, not that the test is -testing all that should be tested against that line of code. +It's important to note that code coverage is only telling you if a test exists, not that the test is +testing all that should be tested against that line of code. -For information on how to add testing to R packages, [R-pkgs.org](https://r-pkgs.org/testing-basics.html) covers -setting up tests with test that. +For information on how to add testing to R packages, [R-pkgs.org](https://r-pkgs.org/testing-basics.html) covers +setting up tests with test that. ## How do I set it up? -You can call this action via adding a call to this job in a github action. A minimal example +You can call this action via adding a call to this job in a github action. A minimal example that runs this on commits to master is: -```bash +```yaml name: Code coverage # sourced from phuse-org/devops-toolkit @@ -65,93 +66,4 @@ jobs: ## The deets -The [`covr`](https://covr.r-lib.org/) R package is used to calculate the -coverage. - -Report summaries and badges for coverage are generated using a series of -other GitHub Actions. - -For this workflow to execute successfully, you will need to create an -orphan branch called `badges` in your GitHub repository. You can do that -using the following steps: - -```bash -# Create orphan branch -git checkout --orphan badges -# Back up files -mv .git /tmp/.git-backup -# Remove everything else -rm -rf * .* -# Restore git files -mv /tmp/.git-backup .git -# Create a README file -echo "# Badges" > README.md -# Add, commit and push your new branch -git add . && git commit -m "Init badges" && git push origin badges -``` - ---- -title: "Check code coverage" -description: | - This workflow measures code coverage for unit tests and reports the code coverage as a percentage of the total number of lines covered by unit tests vs. the total number of lines in the codebase. -categories: - - Testing - - R -author: Pharmaverse -date: 2023-08-01 -image: https://covr.r-lib.org/reference/figures/logo.png -toc: true ---- - -:::{.callout-note style="margin-top: 0rem;" collapse="false"} -## About the gh-action - -**Lifecycle stage:** Not reported - -**Example of use:** [admiral R package](https://github.com/pharmaverse/admiralci#links) - -**Source:** Pharmaverse gh-action maintained by Roche/Genentech - -**Expected output:** Stop or warn in pipeline if links are broken. -::: - -## Why should I use this? - -As your documentation grows, it's likely the number of links present do as well. This -gh-action helps to make sure that if you link to an external website, you can be informed -if that link stops working. - -## How do I set it up? - -You can call this action via adding a call to this job in a github action. A minimal example that runs this on PRs to `main` is: - -```bash ---- -# Source: https://github.com/pharmaverse/admiralci -# Common workflows designed for Admiral -# but can be easily used by any other R package -name: admiral CI/CD Workflows - -on: - push: - branches: - - main - # 'pull_request' events are triggered when PRs are - # created against one of these target branches. - pull_request: - branches: - - main - -jobs: - links: - name: Links - uses: pharmaverse/admiralci/.github/workflows/links.yml@main - if: github.event_name == 'pull_request' -``` - -## The deets - -This gh-action uses lychee. If there are false positives, you can -create a `.lycheeignore` file. There is an example [here of how this is -done in `admiral`](https://github.com/pharmaverse/admiral/blob/devel/.lycheeignore). - +The [`covr`](https://covr.r-lib.org/) R package is used to calculate the coverage. diff --git a/content/cicdworkflows-minimum/posts/pkgdown.qmd b/content/cicdworkflows-minimum/posts/pkgdown.qmd index b0067ee..5e6e714 100644 --- a/content/cicdworkflows-minimum/posts/pkgdown.qmd +++ b/content/cicdworkflows-minimum/posts/pkgdown.qmd @@ -20,22 +20,22 @@ toc: true ## Why should I use this? -`pkgdown` is the most common framework for rendering R package documentation into a an HTML website. This `gh-action` will -generate the documentation, and deploy it to a gh-pages branch. It will also upload a copy of the documentation to the release. +`pkgdown` is the most common framework for rendering R package documentation into a an HTML website. This `gh-action` will +generate the documentation, and deploy it to a gh-pages branch. It will also upload a copy of the documentation to the release. This is important for multiple reasons: 1. Because the documentation is generated automatically, you can make sure the documentation matches the code. Without CICD you are relying on users remembering to rebuild the documentation when they make changes. 1. If you manually generate the documentation, you will need to store the built artefacts in your git repo. This will bloat your repo, and make it harder to work with. -1. Because the documentation is versioned, you can always find the documentation that matches the version of the code you are using. This is important for reproducibility. +1. Because the documentation is versioned, you can always find the documentation that matches the version of the code you are using. This is important for reproducibility. ## How do I set it up? -You can call this action via adding a call to this job in a github action. A minimal example +You can call this action via adding a call to this job in a github action. A minimal example that runs this on commits to main is: -```bash +```yaml --- name: Docs 📚 @@ -52,7 +52,7 @@ jobs: ## The deets -If you have built docs locally in the past, you are probably aware that your git repo will balloon in size, as it stores a copy -of each piece version of every plot and image you have used in your documentation. This `gh-action` will help you avoid that, by +If you have built docs locally in the past, you are probably aware that your git repo will balloon in size, as it stores a copy +of each piece version of every plot and image you have used in your documentation. This `gh-action` will help you avoid that, by placing the versioned documentation into an orphan branch. Helping to keep your docs (a built artefact) seperate from your source code. diff --git a/content/cicdworkflows-minimum/posts/r-cmd-check/r-cmd-check.qmd b/content/cicdworkflows-minimum/posts/r-cmd-check/r-cmd-check.qmd index b2d5662..8b91330 100644 --- a/content/cicdworkflows-minimum/posts/r-cmd-check/r-cmd-check.qmd +++ b/content/cicdworkflows-minimum/posts/r-cmd-check/r-cmd-check.qmd @@ -1,7 +1,7 @@ --- title: "R CMD Check" description: | - Ensure that when you release your package, all the unit tests are passing and it works in a clean environment. + Ensure that when you release your package, all the unit tests are passing and it works in a clean environment. categories: - Testing date: 2023-08-23 @@ -19,9 +19,9 @@ toc: true ## Why should I use this? -`R CMD Check` has [around 50 checks](https://r-pkgs.org/R-CMD-check.html), but the general jist is it will check your package is fit to install, and as part of that process run the unit tests. In many companies, you will -be running potentially multiple versions of R in parrallel. To reflect -that, this gh-action is updated to run across the last 3 R major versions, +`R CMD Check` has [around 50 checks](https://r-pkgs.org/R-CMD-check.html), but the general jist is it will check your package is fit to install, and as part of that process run the unit tests. In many companies, you will +be running potentially multiple versions of R in parrallel. To reflect +that, this gh-action is updated to run across the last 3 R major versions, using a snapshot from the Posit Public Package Manager that reflects a relevant time frame for when that R version was latest. If you have dependencies on other pharmaverse packages, it's likely you will also want to run `R CMD Check` using CRAN today + the bleading edge of the pharmaverse (which may be pre-CRAN) via pointing at their r-universe. If this is the case, please see the advanced usage below. @@ -31,7 +31,7 @@ If you have dependencies on other pharmaverse packages, it's likely you will als Below is an example of using this `gh-action` whenever someone tries to make PR into your `main` or `devel` branch or updates the branch. We recomend you use this on both `main` and `devel` branches, as it will help you catch issues before they get into your main branch. -```bash +```yaml name: Run R-CMD-check # sourced from phuse-org/devops-toolkit diff --git a/content/cicdworkflows-recommend/_metadata.yaml b/content/cicdworkflows-recommend/_metadata.yaml index 606147a..9a99026 100644 --- a/content/cicdworkflows-recommend/_metadata.yaml +++ b/content/cicdworkflows-recommend/_metadata.yaml @@ -1,4 +1,4 @@ comments: - giscus: + giscus: repo: phuse-og/devops category: General diff --git a/content/cicdworkflows-recommend/posts/check-links/check-links.qmd b/content/cicdworkflows-recommend/posts/check-links/check-links.qmd index 406f7e3..50377d4 100644 --- a/content/cicdworkflows-recommend/posts/check-links/check-links.qmd +++ b/content/cicdworkflows-recommend/posts/check-links/check-links.qmd @@ -1,7 +1,7 @@ --- title: "Check links" description: | - This workflow checks whether URLs embedded in code and documentation are valid. Invalid URLs result in workflow failures. + This workflow checks whether URLs embedded in code and documentation are valid. Invalid URLs result in workflow failures. categories: - Documentation - Links @@ -20,7 +20,7 @@ toc: true ## Why should I use this? -As a codebase grows, it becomes more likely you will end up with a number of links in your documentation. +As a codebase grows, it becomes more likely you will end up with a number of links in your documentation. These links can stop working over time - and often you won't know till a user flags your links are broken. This `gh-action` lets you stay on top of broken links, by actively scanning for them. @@ -30,7 +30,7 @@ This `gh-action` lets you stay on top of broken links, by actively scanning for Below is an example of using this `gh-action` whenever someone tries to make PR into your `main` or `devel` branch. -```bash +```yaml name: Check URLs in docs 📚 # sourced from phuse-org/devops-toolkit diff --git a/index.qmd b/index.qmd index 3f7b2d1..d0ea1b0 100644 --- a/index.qmd +++ b/index.qmd @@ -10,7 +10,7 @@ image: assets/PharmaDevOps.png listing: - id: cicdworkflows-minimum - contents: + contents: - /content/cicdworkflows-minimum - "!index.qmd" sort: "date desc" @@ -21,7 +21,7 @@ listing: max-items: 24 feed: false - id: cicdworkflows-recommend - contents: + contents: - /content/cicdworkflows-recommend - "!index.qmd" sort: "date desc" @@ -32,7 +32,7 @@ listing: max-items: 24 feed: false - id: cicdworkflows-enhanced - contents: + contents: - /content/cicdworkflows-enhanced - "!index.qmd" sort: "date desc" @@ -54,13 +54,13 @@ toc: false ::: grid ::: {.g-col-12 .g-col-lg-8 .top-story-text} ## Welcome to the home of **PharmaDevOps** -This PHUSE working group is initially focussed on ensuring R package authors -can easily add CICD to pharmaverse R packages +This PHUSE working group is initially focussed on ensuring R package authors +can easily add CICD to pharmaverse R packages and related biostatistical packages. -Our aim is not to re-invent the wheel. We hope to both -convince package developers of the value of CICD, -provide a minimum bar of what is expected, and provide a +Our aim is not to re-invent the wheel. We hope to both +convince package developers of the value of CICD, +provide a minimum bar of what is expected, and provide a set of tools to make it easy to implement. ::: ::: {.g-col-12 .g-col-lg-4 .top-story-img} @@ -110,16 +110,16 @@ We've also collected togther [this list of external learning resources](post/pos ## Minimum CICD -The following CICD is what we consider a minimum bar for a -package on the pharmaverse. These CICD tools are focussed on -ensuring your package works, and documentation matches the code. +The following CICD is what we consider a minimum bar for a +package on the pharmaverse. These CICD tools are focussed on +ensuring your package works, and documentation matches the code. -There is no need to use the specific code we suggest, if you are happy getting +There is no need to use the specific code we suggest, if you are happy getting the same functionality from another source, like the ones built into `usethis`. - + ::: {#cicdworkflows-minimum} ::: @@ -133,10 +133,10 @@ built into `usethis`. ## Recommended CICD -The following CICD are tools we feel make your life developing and -releasing robust code easier. +The following CICD are tools we feel make your life developing and +releasing robust code easier. - + ::: {#cicdworkflows-recommend} ::: @@ -150,9 +150,9 @@ releasing robust code easier. ## Enhanced CICD -The following CICD are tools are optional tools for power users. +The following CICD are tools are optional tools for power users. - + ::: {#cicdworkflows-enhanced} ::: diff --git a/post/posts/gh-actions.qmd b/post/posts/gh-actions.qmd index 2536437..2028658 100644 --- a/post/posts/gh-actions.qmd +++ b/post/posts/gh-actions.qmd @@ -9,13 +9,13 @@ search: true GitHub Actions are a powerful automation and CI/CD (Continuous Integration/Continuous Deployment) platform provided by GitHub. It allows you to automate various tasks and workflows in response to events that occur in your GitHub repositories. Actions are defined using `YAML` files that specify the workflow to be executed. The workflow file typically has a `.yml` extension. Below is an explanation of the key syntax elements in a GitHub Actions workflow file as an annotated example: ```yaml -# Name: You can specify a name for your workflow. -# This is a human-readable description of the workflow +# Name: You can specify a name for your workflow. +# This is a human-readable description of the workflow # and is not required for the workflow to function. name: My CI/CD Workflow -# on: This specifies the events that trigger the workflow. -# You can set it to various events like pushes to a +# on: This specifies the events that trigger the workflow. +# You can set it to various events like pushes to a # repository, pull requests, or even a schedule. on: push: @@ -25,17 +25,17 @@ on: branches: - master -# jobs: This is the main section of the workflow file. -# It defines the jobs that are to be executed when +# jobs: This is the main section of the workflow file. +# It defines the jobs that are to be executed when # the workflow is triggered. jobs: build: - runs-on: ubuntu-latest # Specifies the type of virtual - # machine or runner on which the job will run. GitHub - # provides various runners for different platforms, + runs-on: ubuntu-latest # Specifies the type of virtual + # machine or runner on which the job will run. GitHub + # provides various runners for different platforms, # including Windows, Linux, and macOS. - steps: # Contains a list of steps that are executed - # in the specified order. Steps are individual + steps: # Contains a list of steps that are executed + # in the specified order. Steps are individual # tasks within a job. - name: Checkout code uses: actions/checkout@v2 From 34521e83d62160014715903eb72f7a29ee2d0a36 Mon Sep 17 00:00:00 2001 From: cicdguy <26552821+cicdguy@users.noreply.github.com> Date: Thu, 22 Feb 2024 06:20:37 -0600 Subject: [PATCH 2/2] docs: Remove references to badges as they are unsupported --- content/cicdworkflows-minimum/posts/code-coverage.qmd | 8 +------- content/cicdworkflows-minimum/posts/pkgdown.qmd | 2 +- post/posts/gh-actions.qmd | 2 +- 3 files changed, 3 insertions(+), 9 deletions(-) diff --git a/content/cicdworkflows-minimum/posts/code-coverage.qmd b/content/cicdworkflows-minimum/posts/code-coverage.qmd index e6fb197..fc2a450 100644 --- a/content/cicdworkflows-minimum/posts/code-coverage.qmd +++ b/content/cicdworkflows-minimum/posts/code-coverage.qmd @@ -15,9 +15,6 @@ toc: true ## About the gh-action **Example of use:** [falcon R package](https://github.com/pharmaverse/falcon/blob/use-phuse-cicd/.github/workflows/phuse-basics.yml) - -**Expected output:** Badge (![Code -Coverage](https://github.com/pharmaverse/admiralci/actions/workflows/code-coverage.yml/badge.svg)) or change pipeline depending on reported code coverage. ::: ## Why should I use this? @@ -26,9 +23,6 @@ This workflow measures code coverage for unit tests and reports the code coverage as a percentage of the *total number of lines covered by unit tests* vs. the *total number of lines in the codebase* in an R package. -Using this github action gives you a badge that helps to show that the code is coverage. Calculating this -via CICD is useful as the amount of untested code can vary, e.g. a new feature is added but it is not tested. People often use this metric as an indicator of code quality and maturity. - It's important to note that code coverage is only telling you if a test exists, not that the test is testing all that should be tested against that line of code. @@ -37,7 +31,7 @@ setting up tests with test that. ## How do I set it up? -You can call this action via adding a call to this job in a github action. A minimal example +You can call this action via adding a call to this job in a GitHub Actions workflow. A minimal example that runs this on commits to master is: ```yaml diff --git a/content/cicdworkflows-minimum/posts/pkgdown.qmd b/content/cicdworkflows-minimum/posts/pkgdown.qmd index 5e6e714..f223393 100644 --- a/content/cicdworkflows-minimum/posts/pkgdown.qmd +++ b/content/cicdworkflows-minimum/posts/pkgdown.qmd @@ -32,7 +32,7 @@ This is important for multiple reasons: ## How do I set it up? -You can call this action via adding a call to this job in a github action. A minimal example +You can call this action via adding a call to this job in a GitHub Actions workflow. A minimal example that runs this on commits to main is: ```yaml diff --git a/post/posts/gh-actions.qmd b/post/posts/gh-actions.qmd index 2028658..df3e895 100644 --- a/post/posts/gh-actions.qmd +++ b/post/posts/gh-actions.qmd @@ -1,7 +1,7 @@ --- pagetitle: ghactions title: The anatomy of a gh-action -subtitle: "Understanding what makes a github action tick" +subtitle: "Understanding what makes a GitHub Actions workflow tick" date: 2023-10-23 search: true ---