Merge pull request #1515 from opensafely/iaindillingham/how-to-add-co…

…despaces

Add "How to add Codespaces to your project" page

docs/getting-started/how-to/add-github-codespaces-to-your-project/index.md

@@ -0,0 +1,126 @@
+This page describes how to add GitHub Codespaces to your project.
+
+## Does your project already have GitHub Codespaces?
+
+Newer projects already have GitHub Codespaces.
+However, older projects don't.
+To find out whether your project is newer or older:
+
+* Click on your project in the [opensafely](https://github.com/opensafely) organisation on GitHub.
+* Can you see a `.devcontainer` folder?
+  If not, then your project is **older**.
+* Click on the `.devcontainer` folder to open it.
+* Click on the `devcontainer.json` file to open it.
+* Can you see the following line towards the top of the file?
+  If not, then your project is **older**.
+  ```json
+  "image": "ghcr.io/opensafely-core/research-template:v0",
+  ```
+* If you've got this far, then your project is **newer**.
+
+## Adding GitHub Codespaces to your project
+
+We will use Git to add GitHub Codespaces to your project.
+There are many ways to use Git.
+For example, we could use Git with the `git` command-line tool, with GitHub Desktop, or with VS Code.
+Here, we will use Git with `git`, because `git` commands are succinct.
+The documentation for
+[GitHub Desktop](https://docs.github.com/en/desktop) and
+[VS Code](https://code.visualstudio.com/docs/sourcecontrol/overview)
+describes how to translate `git` commands into equivalent user-interface commands.
+
+Here, you will run `git` commands on your computer.
+
+### Identify your project's working branch
+
+The *working branch* contains work that is "done".
+It is often called `main` and it is often associated with a workspace on OS Jobs.
+
+We will add GitHub Codespaces to the working branch.
+
+### Create a new branch
+
+Switch to the working branch:
+
+```sh
+git switch <working branch>
+```
+
+Create a new branch called `github-codespaces`:
+
+```sh
+git switch --create=github-codespaces
+```
+
+### Copy files
+
+* Visit the [opensafely/research-template](https://github.com/opensafely/research-template) project on GitHub.
+* Click on the `.devcontainer` folder to open it.
+* Click on the first file to open it.
+* Click on "Download raw file" (![The "Download raw file" icon](download_raw_file.png)) to download the first file to your computer.
+* Repeat for the remaining files.
+* Copy each file to the `.devcontainer` folder in your project.
+
+!!! info "My project doesn't have a `.devcontainer` folder"
+    If your project doesn't have a `.devcontainer` folder,
+    then create one.
+    It's important that it starts with a dot (`.`).
+
+### Commit and push
+
+Commit the files you copied in the previous step:
+
+```sh
+git commit --message='Add GitHub Codespaces'
+```
+
+Push to GitHub:
+
+```sh
+git push
+```
+
+### Create a pull request
+
+* Click on your project in the [opensafely](https://github.com/opensafely) organisation on GitHub.
+* Click on "Pull requests".
+* Click on "New pull request".
+* Beneath "Compare changes" there are two boxes labelled "base" and "compare".
+    * The "base" box should contain the name of the working branch.
+    * The "compare" box should contain `github-codespaces`.
+* Click on "Create pull request".
+
+### Approve and merge the pull request
+
+* Click on "Files changed"
+* Click on "Review changes"
+* Click on "Approve"
+* Click on "Submit review"
+* Click on "Merge pull request"
+
+### Housekeeping
+
+Switch to the working branch:
+
+```sh
+git switch <working branch>
+```
+
+Pull from GitHub:
+
+```sh
+git pull
+```
+
+Delete the `github-codespaces` branch:
+
+```sh
+git branch --delete github-codespaces
+```
+
+### Start a Codespace
+
+The
+"[How to use GitHub Codespaces in your project](../use-github-codespaces-in-your-project/index.md)"
+page has more information about using GitHub Codespaces in your project,
+including how to start a Codespace :rocket:.

docs/getting-started/how-to/index.md

@@ -2,6 +2,7 @@ The how-to guides provide practical steps for setting up and using OpenSAFELY.
 
 ## Using OpenSAFELY
 
+* [How to add GitHub Codespaces to your project](add-github-codespaces-to-your-project/index.md)
 * [How to use GitHub Codespaces in your project](use-github-codespaces-in-your-project/index.md)
 * [How to use GitHub and Git](../../install-github-and-git.md)
 * [How to use the OpenSAFELY command-line interface](../../opensafely-cli.md)

mkdocs.yml

@@ -33,6 +33,7 @@ nav:
         - See the next steps: getting-started/tutorial/see-the-next-steps/index.md
       - How-to guides:
         - How-to guides: getting-started/how-to/index.md
+        - How to add GitHub Codespaces to your project: getting-started/how-to/add-github-codespaces-to-your-project/index.md
         - How to use GitHub Codespaces in your project: getting-started/how-to/use-github-codespaces-in-your-project/index.md
         - How to use GitHub and Git: install-github-and-git.md
         - How to use the OpenSAFELY command-line interface: opensafely-cli.md