Add a first pass explanation of using GitHub Codespaces for OpenSAFELY projects

[StevenMaude]

This adds a first pass explanation of using GitHub Codespaces with the research template.

It follows:

opensafely/research-template#102

which is now merged.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Pages

Latest commit:	119231c
Status:	✅  Deploy successful!
Preview URL:	https://5226f4aa.opensafely-docs.pages.dev
Branch Preview URL:	https://steve-github-codespaces-basi.opensafely-docs.pages.dev

View logs

[StevenMaude]

TODO:

• merge research template PR
• work through steps and see if they work end-to-end
• add screenshots
• tidy commits

[StevenMaude]

The commits need tidying here, and one of the images has a half-visible tool tip, which could be fixed.

[StevenMaude]

Preview content is at: https://steve-github-codespaces-basi.opensafely-docs.pages.dev/github-codespaces/

[StevenMaude]

I think ultimately this page is serving three current purposes, and would eventually split into:

• the Getting Started page (but with some extra tidying/refinement)
• a separate page on managing Codespaces and Codespaces billing
• a separate page on the full set of features we provide in the Codespaces setup

It's fine as one self-contained page for now, until we work this out.

[StevenMaude]

Things that aren't discussed in this documentation, or have been thought too much about. They could be considered more in future:

• codespace prebuilds
  • These speed up the codespace deployment, but not sure how these would work inside an organization.
  • Not sure how these interact with template-created repositories either.
  • They cost money for an organization, because they use storage.
• debugging issues with Codespaces
  • can users access Codespaces at all, or does IT policy prevent access?
  • GitHub still occasionally has big outages unfortunately, roughly 1-3 times per month; check GitHub's status page if Codespaces is unavailable or behaving strangely
• more on configuring machines appropriately
  • how to spot out of memory errors
• the "unpublished changes" warning when deleting a codespace
  • you can save these changes to a branch when deleting a codespace
• hiding unhelpful ehrQL autocompletion suggestions of internal attributes/methods
  • not sure how we do this in Visual Studio Code: Support hiding "private" variables/attributes for auto complete  microsoft/pylance-release#5281
• keeping the installed ehrQL in sync with the ehrQL version you're using for your project
  • for now, I've not worried about this too much and it's a bit out of scope
  • the latest main version gets installed
  • we might solve it by having a v1, v2 branch, or publishing an ehrQL package to PyPI
  • not sure what the behaviour is on restarting the existing codespace;
    • it might reinstall packages as this is a post-container command, and needs checking
• updating OpenSAFELY CLI
  • may not really need to do manually; you might be able to just stop and start the codespace?
• use of Codespaces with a local Visual Studio Code installation
  • it removes the web browser, which again might help to remove quirks/bugs
  • you can install Visual Studio Code as a "user setup", without admin permissions, I think

[StevenMaude]

We should update the "Downloading some dummy data" title in the ehrQL documentation, because there's no download involved, but will update that later.