diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000..9bd55e9 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,9 @@ +// Config options: https://github.com/rocker-org/devcontainer-templates/tree/main/src/r-ver +{ + "name": "R Package Dev Prebuilt (rocker/r-ver base)", + // Image to pull when not building from scratch. + // See .github/devcontainer/devcontainer.json for build details + // and .github/workflows/pre-build-devcontainer.yml for how the + // image is built using GitHub Actions/CI + "image": "ghcr.io/coatless-devcontainer/r-pkg:latest" +} diff --git a/.github/.devcontainer/devcontainer.json b/.github/.devcontainer/devcontainer.json new file mode 100644 index 0000000..fc0e2d4 --- /dev/null +++ b/.github/.devcontainer/devcontainer.json @@ -0,0 +1,61 @@ +// Config options: https://github.com/rocker-org/devcontainer-templates/tree/main/src/r-ver +{ + "name": "R Package Dev (rocker/r-ver base)", + "image": "ghcr.io/rocker-org/devcontainer/r-ver:4.4", + // Add software + "features": { + // Rig configuration: https://github.com/rocker-org/devcontainer-features/blob/main/src/r-rig/README.md + "ghcr.io/rocker-org/devcontainer-features/r-rig:1": { + "installDevTools": true, + "installRadian": true, + "installVscDebugger": true, + "installRMarkdown": true, + "vscodeRSupport": "full" + } + }, + "customizations": { + "vscode": { + // Ensure VS Code extensions for R are present + "extensions": [ + // R Extensions + "rdebugger.r-debugger", + "reditorsupport.r", + // Quarto + "quarto.quarto", + // LLM + "GitHub.copilot" + ] + }, + // Customize R settings + "settings": { + "editor.wordWrap": "wordWrapColumn", + "r.rterm.linux": "/usr/local/bin/radian", + "r.bracketedPaste": true, + "r.plot.useHttpgd": true, + // Settings by language + "[r]": { + "editor.wordSeparators": "`~!@#%$^&*()-=+[{]}\\|;:'\",<>/?", + "editor.defaultFormatter": "REditorSupport.r", + "editor.snippetSuggestions": "top" + }, + "[rmd]": { + "editor.defaultFormatter": "REditorSupport.r", + "editor.snippetSuggestions": "top" + }, + "[quarto]": { + "editor.defaultFormatter": "quarto.quarto", + "editor.snippetSuggestions": "top" + }, + // Enable suggestions + "github.copilot.enable": { + "quarto": true, + "*": true + } + } + }, + // Enable pak using system package manager + // https://github.com/rocker-org/devcontainer-features/blob/main/src/r-rig/README.md#install-r-packages-via-pak + "remoteEnv": { + "PKG_SYSREQS": "true" + } +} diff --git a/.github/workflows/pre-build-devcontainer.yml b/.github/workflows/pre-build-devcontainer.yml new file mode 100644 index 0000000..d190b0b --- /dev/null +++ b/.github/workflows/pre-build-devcontainer.yml @@ -0,0 +1,38 @@ +name: 'build' +on: # rebuild any PRs and main branch changes + pull_request: + branches: + - main + push: + branches: + - main + workflow_dispatch: {} + +jobs: + build: + runs-on: ubuntu-latest + permissions: + contents: read + packages: write + env: + CONTAINER_OWNER: ${{ github.repository_owner }} + CONTAINER_NAME: ${{ github.event.repository.name }} + steps: + + - name: Checkout (GitHub) + uses: actions/checkout@v3 + + - name: Login to GitHub Container Registry + uses: docker/login-action@v2 + with: + registry: ghcr.io + username: ${{ env.CONTAINER_OWNER }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Pre-build dev container image + uses: devcontainers/ci@v0.3 + with: + subFolder: .github + imageName: ghcr.io/${{ env.CONTAINER_OWNER }}/${{ env.CONTAINER_NAME }} + cacheFrom: ghcr.io/${{ env.CONTAINER_OWNER }}/${{ env.CONTAINER_NAME }} + push: always diff --git a/README.md b/README.md new file mode 100644 index 0000000..f4af52f --- /dev/null +++ b/README.md @@ -0,0 +1,60 @@ +# r-pkg + +This repository houses a devcontainer that setups an R package development environment. The container is setup to work with [GitHub Codespaces](https://github.com/features/codespaces) to instantly have a cloud-based developer workflow. + +You can try out the Codespace by clicking on the following button: + +[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/coatless-devcontainer/r-pkg?quickstart=1) + +> [!NOTE] +> +> Codespaces are available to Students and Teachers for free [up to 180 core hours per month](https://docs.github.com/en/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/using-github-codespaces-with-github-classroom#about-github-codespaces) +> through [GitHub Education](https://education.github.com/). Otherwise, you will have +> [up to 60 core hours and 15 GB free per month](https://github.com/features/codespaces#pricing). + +Or, you can press the template button to create a new repository with the same setup so that you +can work locally on the devcontainer: + +[![Use this template](https://img.shields.io/badge/Use%20this%20template-Create%20new%20repository-blue?logo=github)](https://github.com/coatless-devcontainer/r-pkg/generate) + +This will create a fork of the repository that can be worked on inside a local copy of +[Visual Studio Code](https://code.visualstudio.com/) through the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers). With the extension installed, you can open the repository in a container by pressing `F1` (to bring up command palette) and typing `Dev Container: Reopen in Container`. + +Lastly, you can directly obtain the underlying container image by typing in Terminal: + +```sh +docker pull ghcr.io/coatless-devcontainer/r-pkg:latest +``` + +## Quick start + +Run the following series of commands inside of R once the container opens. Make sure to change `"name-of-package"` to your current package name. + +```r +usethis::create_package("name-of-package") +usethis::use_package_doc() +usethis::use_agpl3_license() +usethis::use_testthat() +usethis::use_github_action("check-standard") +usethis::use_pkgdown_github_pages() +``` + +## Resources + +- [Manual: Writing R extensions](https://cran.r-project.org/doc/manuals/r-release/R-exts.html) +- [Textbook: R Packages](https://r-pkgs.org/) +- [usethis](https://usethis.r-lib.org/) +- [devtools](https://devtools.r-lib.org/) + +## Developer notes + +This repository uses a pre-built container strategy to have GitHub Actions build and, then, store the devcontainer in [GitHub's Container Repository](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry). + +We place the main logic of the devcontainer in [`.github/.devcontainer/devcontainer.json`](https://github.com/coatless-devcontainer/r-pkg/blob/main/.github/.devcontainer/devcontainer.json). From there, we use [`.github/workflows/pre-build-devcontainer.yml`](https://github.com/coatless-devcontainer/r-pkg/blob/main/.github/workflows/pre-build-devcontainer.yml) to build and publish the devcontainer onto GitHub's Container repository for the organization. Then, the repository's [`.devcontainer/devcontainer.json`](https://github.com/coatless-devcontainer/r-pkg/blob/main/.devcontainer/devcontainer.json) pulls the pre-built image. + +> [!IMPORTANT] +> +> Make sure to specify the permissions as stated in the GitHub Actions workflow linked above +> and for organizations please make sure to have the organization's container registry enabled. +> +> For more information, see [GitHub's Container Registry documentation](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry). \ No newline at end of file