diff --git a/content/cicdworkflows-enhanced/_metadata.yaml b/content/cicdworkflows-enhanced/_metadata.yaml new file mode 100644 index 0000000..606147a --- /dev/null +++ b/content/cicdworkflows-enhanced/_metadata.yaml @@ -0,0 +1,4 @@ +comments: + giscus: + repo: phuse-og/devops + category: General diff --git a/content/cicdworkflows-enhanced/index.qmd b/content/cicdworkflows-enhanced/index.qmd new file mode 100644 index 0000000..3494ed1 --- /dev/null +++ b/content/cicdworkflows-enhanced/index.qmd @@ -0,0 +1,15 @@ +--- +pagetitle: Enhanced CICD workflows +title: Enhanced CICD workflows +subtitle: CICD workflows for power users +search: false +listing: + contents: posts + sort: "date desc" + type: grid + categories: true + sort-ui: true + filter-ui: true + page-size: 12 +comments: false +--- \ No newline at end of file diff --git a/content/cicdworkflows-enhanced/posts/validate/validate.jpg b/content/cicdworkflows-enhanced/posts/validate/validate.jpg new file mode 100644 index 0000000..a395769 Binary files /dev/null and b/content/cicdworkflows-enhanced/posts/validate/validate.jpg differ diff --git a/content/cicdworkflows-enhanced/posts/validate/validate.qmd b/content/cicdworkflows-enhanced/posts/validate/validate.qmd new file mode 100644 index 0000000..22c5430 --- /dev/null +++ b/content/cicdworkflows-enhanced/posts/validate/validate.qmd @@ -0,0 +1,59 @@ +--- +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. +categories: + - Testing + - Documentation + - Validation +date: 2023-08-01 +image: validate.jpg +toc: true +--- + +:::{.callout-note style="margin-top: 0rem;" collapse="false"} +## About the gh-action + +**Example of use:** [admiral R package](https://github.com/insightsengineering/thevalidatoR/blob/main/readme_files/report-0.1-admiral.pdf) + +**Expected output:** A PDF attached to a release. +::: + +## 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. +These links can over time stop working - and often you won't know till a user flags your links or broken. + +This `gh-action` lets you stay on top of broken links, by actively scanning for them. + +## How do I set it up? + +Below is an example of using this `gh-action` whenever someone tries to make PR into your `main` or `devel` branch. + + +```bash +--- +name: Docs 📚 + +on: + push: + branches: + - main + - devel + pull_request: + branches: + - main + - devel + +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 you need to prevent false positive deadlinks stopping the +process, you can use a `.lycheeignore` file. There is an example of this file [from +admiral here](https://github.com/pharmaverse/admiral/blob/devel/.lycheeignore). diff --git a/content/cicdworkflows-minimum/_metadata.yaml b/content/cicdworkflows-minimum/_metadata.yaml index 4e213a7..606147a 100644 --- a/content/cicdworkflows-minimum/_metadata.yaml +++ b/content/cicdworkflows-minimum/_metadata.yaml @@ -1,4 +1,4 @@ comments: giscus: - repo: realworlddatascience/realworlddatascience.github.io + 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 faddffc..c705c53 100644 --- a/content/cicdworkflows-minimum/posts/code-coverage.qmd +++ b/content/cicdworkflows-minimum/posts/code-coverage.qmd @@ -26,7 +26,7 @@ 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. +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. diff --git a/content/cicdworkflows-minimum/posts/pkgdown.qmd b/content/cicdworkflows-minimum/posts/pkgdown.qmd index ef95972..789f067 100644 --- a/content/cicdworkflows-minimum/posts/pkgdown.qmd +++ b/content/cicdworkflows-minimum/posts/pkgdown.qmd @@ -20,9 +20,14 @@ toc: true ## Why should I use this? -`pkgdown` is the most common framework for rendering R package documentation into a an HTML website. - Generating and uploading documentation manually makes it very easy for differences -to be present +`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. ## How do I set it up? 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 2e8c39f..448a3ca 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 @@ -30,7 +30,7 @@ If you have dependencies on other pharmaverse packages, it's likely you will als ## How do I set it up? -Below is an example of using this `gh-action` whenever someone tries to make PR into your `main` or `devel` branch. +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 diff --git a/content/cicdworkflows-recommend/_metadata.yaml b/content/cicdworkflows-recommend/_metadata.yaml index 4e213a7..606147a 100644 --- a/content/cicdworkflows-recommend/_metadata.yaml +++ b/content/cicdworkflows-recommend/_metadata.yaml @@ -1,4 +1,4 @@ comments: giscus: - repo: realworlddatascience/realworlddatascience.github.io + 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 99ca489..cfec89e 100644 --- a/content/cicdworkflows-recommend/posts/check-links/check-links.qmd +++ b/content/cicdworkflows-recommend/posts/check-links/check-links.qmd @@ -55,4 +55,4 @@ jobs: This gh-action uses lychee. If you need to prevent false positive deadlinks stopping the process, you can use a `.lycheeignore` file. There is an example of this file [from -admiral here](https://github.com/pharmaverse/admiral/blob/devel/.lycheeignore). \ No newline at end of file +admiral here](https://github.com/pharmaverse/admiral/blob/devel/.lycheeignore). diff --git a/index.qmd b/index.qmd index d7d36da..8f62f46 100644 --- a/index.qmd +++ b/index.qmd @@ -31,6 +31,17 @@ listing: filter-ui: false max-items: 24 feed: false + - id: cicdworkflows-enhanced + contents: + - /content/cicdworkflows-enhanced + - "!index.qmd" + sort: "date desc" + type: grid + categories: true + sort-ui: false + filter-ui: false + max-items: 24 + feed: false toc: false --- @@ -65,14 +76,23 @@ the domain of devops, by data scientists, in late-stage drug development. ::: grid ::: {.g-col-12 .top-story-text} ## Getting started with CICD + +In this guidance, you'll see a number of `gh-actions` that you can use to implement CICD on your project. We have categorised these into three groups: + +- *Minimum CICD*: These are the minimum CICD tools we recommend for all packages on the pharmaverse. These CICD tools are focussed on ensuring your package works, and documentation matches the code. +- *Recommended CICD*: These are tools we feel make your life developing and releasing robust code easier. +- *Enhanced CICD*: These are tools are option tools for power users, or those with specific needs. + +Each CICD action is described via a common pattern, with an emphasis on why we recommend it, and how to use it. + A recomended plan for success in implenting CICD on your project is to: -- Read this post on the general anatomy of a `gh-action` [TODO] +- [Read this post](post/posts/gh-actions.html) on the general anatomy of a `gh-action` - Browse our recomended `gh-action`'s below - Review this case study of CICD is used in `admiral` - Implement CICD on your git repo! -We've also collected togther this list of external learning resources here: [TODO] +We've also collected togther [this list of external learning resources](post/posts/external-resources.html).