WIP: Add a basic explanation of GitHub Codespaces

This is still an experiment, and depends on:

opensafely/research-template#102

being merged to make this work.

docs/github-codespaces.md

@@ -0,0 +1,194 @@
+!!! warning
+
+    GitHub Codespaces support is still being tested.
+    This documentation is subject to change.
+
+The OpenSAFELY research template contains a configuration
+to allow you to run OpenSAFELY
+**without any installation required on your own computer**.
+
+This uses GitHub Codespaces.
+
+## What is GitHub Codespaces?
+
+[Codespaces](https://github.com/features/codespaces) is a coding environment
+hosted online by GitHub.
+Codespaces can be accessed via your web browser
+without any additional installation.
+
+A codespace provides:
+
+* a "virtual machine" — a computer running as software inside another computer
+  — that is hosted by GitHub
+* a Visual Studio Code environment
+  for editing your project and running commands
+
+When you open a codespace in browser,
+you get access to the Visual Studio Code environment.
+Through that interface,
+you can run commands inside the codespace's virtual machine.
+This is just as if it were a real desktop or laptop that you were working on,
+but does not require any installation.
+
+This removes the need to have anything other than a web browser installed
+to work on OpenSAFELY projects.
+
+## Create a GitHub account
+
+Before starting with OpenSAFELY in GitHub Codespaces,
+you will need a free GitHub account:
+
+1. Create a free GitHub account,
+   if you do not already have one.
+1. Login to that GitHub account.
+
+## Working on OpenSAFELY projects via GitHub Codespaces
+
+To start a Codespace,
+you need to create a code repository that you can launch a codespace from.
+
+We will use the OpenSAFELY research template
+as a basis for our code.
+
+### Create a code repository for your work
+
+You only need to create a code repository once for a particular project:
+
+1. Create a new research code repository *under your own username*
+   based on the research template.
+
+!!! warning
+
+    This step will enable you to work on your code in Codespaces,
+    and check that it would work with OpenSAFELY.
+
+    **It will not allow you to run code on OpenSAFELY's platform.**
+
+    For that, you would have to request that your repository is transferred to the `opensafely` organization.
+    Existing OpenSAFELY users typically create a repository within the `opensafely` organization.
+
+### Launch a codespace
+
+Once you have a code repository created,
+you can launch a codespace from that repository:
+
+1. Navigate to the newly created research repository.
+1. Click the "Code" button
+1.
+
+### Navigating the codespace
+
+When this finishes launching,
+you should see a Visual Studio Code editor with three panes:
+
+* on the left, the file explorer
+* a terminal at the bottom-right
+* a file editor at the upper-right
+
+### Editing code
+
+The file explorer shows the contents of your code repository.
+You can open files by double-clicking them.
+
+### Updating files in the repository
+
+This is a two-step process.
+
+1. Save a file in Visual Studio Code.
+   This only saves the file locally inside the Codespace.
+   These changes will not yet show up in your GitHub code repository.
+1. Use the Source Control view to add, commit and publish those changes
+   to your GitHub repository.
+   If you are unfamiliar with Visual Studio Code and GitHub,
+   [GitHub has a guide on using this](https://docs.github.com/en/codespaces/developing-in-codespaces/using-source-control-in-your-codespace#committing-your-changes).
+
+## A quick guide to OpenSAFELY features
+
+Now that we have a GitHub codespace running,
+we can use OpenSAFELY.
+
+Here is a short and non-exhaustive guide to how things work.
+
+### Running the OpenSAFELY CLI
+
+* You can run the OpenSAFELY CLI in GitHub Codespaces.
+  In the Visual Studio Code terminal, type `opensafely` and press ++Enter++.
+
+* See the OpenSAFELY CLI documentation for more.
+
+###
+
+### GitHub Codespaces computer resources
+
+The default codespace has 2 computer processor cores (CPU cores) and 4 GB memory (RAM).
+In some cases,
+you may find that OpenSAFELY projects exceed the available RAM.
+
+GitHub Codespaces does have virtual machines with more CPU cores and RAM,
+but these will use the free quota more quickly.
+
+It is possible to configure what virtual machine type the codespace has when launching the codespace.
+See [GitHub's explanation of configuring advanced options](https://docs.github.com/en/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository?tool=webui#creating-a-codespace-for-a-repository) for a codespace.
+
+It is also possible to [change a virtual machine type for an existing codespace](https://docs.github.com/en/codespaces/customizing-your-codespace/changing-the-machine-type-for-your-codespace#changing-the-machine-type).
+
+## GitHub Codespaces billing
+
+GitHub gives all users a free and decent-sized monthly quota for Codespaces.
+This is accessible without a paid account.
+See [GitHub's pricing details](https://docs.github.com/en/billing/managing-billing-for-github-codespaces/about-billing-for-github-codespaces).
+
+!!! note
+
+    You will not get billed for using Codespaces,
+    unless you both:
+
+    * set a Codespaces spending limit
+    * and add a payment method
+
+    Without billing configured,
+    if you run out of free quota,
+    GitHub will only block you from using Codespaces until the next monthly cycle starts.
+
+### Managing codespaces
+
+If you close a codespace in your browser,
+it still continues running.
+You can return to an open codespace from the code repository.
+
+It is useful to stop or delete codespaces to prevent them from using your quota unnecessarily.
+
+#### Stopping a codespace
+
+See GitHub's documentation for how to stop a codespace.
+
+This stops a codespace running,
+but allows you to restart it.
+
+Stopped codespaces still incur storage usage.
+
+#### Deleting a codespace
+
+See GitHub's documentation for how to delete a codespace.
+
+Unlike *stopping* a codespace,
+this removes the codespace entirely,
+
+Once deleted,
+
+#### Idle timeout
+
+A codespace will eventually stop when it is not being used..
+This is a useful feature to prevent you from wasting free or paid Codespaces credit.
+This setting can be configured to give a longer or shorter duration.
+[See the GitHub documentation](https://docs.github.com/en/codespaces/customizing-your-codespace/setting-your-timeout-period-for-github-codespaces).
+
+
+!!! info
+
+    We are still investigating how we can make Codespaces more useful
+    for researchers working on OpenSAFELY projects.
+
+    Please feel free to ask us questions,
+    tell us about problems you find,
+    or give us any other feedback.

mkdocs.yml

@@ -35,6 +35,7 @@ nav:
           - Overview: install-intro.md
           - Managing Gitpod workspaces: gitpod-workspaces.md
           - GitHub and Git: install-github-and-git.md
+          - Running OpenSAFELY in GitHub Codespaces: github-codespaces.md
           - Python: install-python.md
           - Docker: install-docker.md
           - OpenSAFELY CLI: opensafely-cli.md