Add documentation on using GitHub Codespaces (#13760)

* Add documentation on using GitHub Codespaces

Signed-off-by: Matty Stratton <[email protected]>

* Update README.md

---------

Signed-off-by: Matty Stratton <[email protected]>

Author: mattstratton

README.md

@@ -6,7 +6,8 @@
 This is the repo for managing [devopsdays.org](http://www.devopsdays.org).
 
 [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/devopsdays/devopsdays-web)<br>
-[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/devopsdays/devopsdays-web)
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/devopsdays/devopsdays-web)<br>
+(See [Using Codespaces](utilities/docs/using-codespaces/README.md) for more information)
 
 ## Managing your event content
 

utilities/README.md

@@ -1,4 +1,5 @@
 # Utilities
+
 These scripts help devopsdays organizers manage their events.
 
 ## Contributing
@@ -43,6 +44,7 @@ Many sponsors are sponsors for multiple devopsdays. If a sponsor listing already
 The sample datafile has some sponsor levels pre-populated; edit as desired. You will want to decide what's in your sponsor packages before accepting most types of sponsors (other than Community).
 
 #### Sponsor URL override
+
 Sometimes, an existing sponsor will want an event-specific URL for your event. Rather than creating a new sponsor, you can add an optional `url` field to the sponsor in your event data file to override the default URL for that sponsor. For example:
 
 ```
@@ -75,6 +77,7 @@ Modifying 2018-chicago/contact/index.html
 ```
 
 Under the hood, the script is:
+
 1. Copying the existng sponsor files to `sponsor-before-todaysdate.{png,yml}`.
 1. Copying in the new image to `sponsor.png`.
 1. Modifying any events that did _not_ occur this year such that they are sponsored by `sponsor-before-todaysdate`, rather than `sponsor`.
@@ -86,7 +89,6 @@ Finally, make whatever changes are requested to the image and data file.
 
 See [Pivotal logo update](https://github.com/devopsdays/devopsdays-web/pull/6501) for the pull request that inspired this example.
 
-
 ### Adding a new sponsor
 
 Use [add_sponsors.sh](add_sponsors.sh) to easily add new sponsors. (Only do this if the sponsor doesn't already exist.)
@@ -97,7 +99,6 @@ Use [add_sponsors.sh](add_sponsors.sh) to easily add new sponsors. (Only do this
 
 See [contrib/make_sponsors.rb](make_sponsors.rb) for another option.
 
-
 ### Sponsor logos
 
 Guidelines regarding sponsor logo files and formatting:
@@ -118,7 +119,6 @@ The organizer photo must be in JPG format, and should be a minimum 300px x 300px
 
 Any PRs adding a new local organizer will need to be accompanied by an email to `[email protected]` with their full name and email address. We merge the PR at the same time as adding them to email lists and Slack, so if you aren't ready to send that email, merging your PR will be delayed until we have that info.
 
-
 ## Social sharing image
 
 A sharing image is added to the Open Graph tags for your event pages, to improve the sharing on social networks such as Facebook (or in Slack). This image must located in `static/events/yyyy-city/sharing/`. It should be a minimum 1200px x 630px, and use ratio: 1.91:1. You must set the `sharing_image` field in `data/events/yyyy-city.yml` (example: `sharing_image: "sharing.jpg"`). You can also override the sharing image by setting `sharing_image` in the frontmatter of a specific page, with the filename of an image in the `static/events/yyyy-city/sharing/` directory. Example: `sharing_image = "jeff-smith.png"`
@@ -148,19 +148,16 @@ Speakers = ["rainbow-dash","twilight-sparkle"]
 
 You can also rename the generated program file to include them both: `mv content/events/2017-ponyville/program/rainbow-dash.md content/events/2017-ponyville/program/dash-sparkle.md`. As long as the Speakers line is set correctly, this will work fine.
 
-
 ### Program
 
 Use [add_program.sh](add_program.sh) to add the program for your event. The program template expects 4 full talks each day and lists default times, but you can customize. The program data is stored in the event datafile such as `data/events/2017-ponyville.yml`. You don't need to know any or all of your speakers when adding the sample program, but if you have selected speakers you can list them on the program with this script.
 
 If you start working on the program before you have all your speakers, by default you'll have `talk-1` through `talk-8` and you can replace those with slugs like `rainbow-dash` or `dash-sparkle` as appropriate.
 
-
 ### Speaker Images
 
 The headshots for your speaker images can be either .png or .jpg. They should be square, preferably 600px square. If they are not square, the page listing all speakers will crop them to square, but the individual speaker and talk pages will not crop the image). 
 
-
 # Adding slides and video
 
 After the event, you can set additional optional frontmatter for talk files such as `content/events/2017-ponyville/program/rainbow-dash.md`:
@@ -174,6 +171,7 @@ slides = ""
 ```
 
 ## Embedding Videos Other than Vimeo or YouTube
+
 You can embed video other than YouTube or Vimeo on talk pages by adding the embed script to a talk file (such as `content/events/2017-ponyville/program/rainbow-dash.md`) and enclosing it into a `<div>` section. Here is an example of embedding a SlidesLive.com video:
 ```
 +++
@@ -191,7 +189,6 @@ You can embed video other than YouTube or Vimeo on talk pages by adding the embe
 
 ```
 
-
 # Bash tips:
 
 Set `$DOD_YEAR` and `$DOD_CITY` and the scripts won't ask

utilities/docs/using-codespaces/README.md

@@ -0,0 +1,74 @@
+# Using GitHub Codespaces with devopsdays-web
+
+*This is a work in progress and the document may not be comprehensive. Pull requests welcome!*
+
+GitHub Codespaces allows you to do all the editing and changes to your files on the devopsdays website without having to run hugo or anything locally! It even works with the utility scripts.
+
+## Getting started
+
+Begin by going to [github.com/devopsdays/devopsdays-web](github.com/devopsdays/devopsdays-web) and on the README, click the "Open in GitHub Codespaces" button:
+
+![](img/codespaces-button.png)
+
+This will take you to a screen to set up the Codespace:
+
+![Codespaces setup](img/codespace-setup.png)
+
+Do not change the settings for Repository, Branch, Dec container configuration, or Machine type. You can select a Region that is closest to you. Click "Create Codespace".
+
+This will take a few minutes to set up. Once it is ready, you will see a screen like this:
+[![Codespaces ready](img/codespace-tn.png)](img/codespace-full.png)
+
+You may see a message at the bottom like this:
+
+![Codespaces message](img/port-prompt.png)
+
+If you click on the "Open in browser" link, you will see the site in your browser.
+
+If you do not see this message, you can always find the URL for the site in the "ports" section:
+
+![](img/ports-arrrow.png)
+
+![](img/forward-address.png)
+*Click on the link to see options for opening the site in a browser.*
+
+## Running commands
+
+If you need to run any terminal commands (i.e., one of the utility scripts), you can open a terminal by clicking on the "Terminal" tab and then selecting the "bash" tab:
+
+![bash prompt](img/bash.png)
+
+## Committing changes
+
+When you have made any changes you need, you will want to commit them to git and push them to your fork. 
+
+You can do this by clicking on the "Source Control" tab on the left-hand side of the screen. 
+
+![](img/git-nav.png)
+*The Source Control tab is the third from the top. If there are uncommitted changes, it will identify this with a badge, like this one that shows "11"*
+
+This will show you all the files that have been changed. You can stage the files you want to commit by clicking on the "+" next to the file name. Then you can enter a commit message and click the green "Commit" button to commit the changes.
+
+![](img/commits.png)
+
+Now you can just push "Publish branch" to push the changes to your fork.
+
+![](img/publish.png)
+
+Make sure you push to your fork and not the main repository!
+
+![](img/origin.png)
+
+Now you can create a pull request to merge your changes into the main repository, the same way you would with any other method.
+
+## Stopping your codespace
+
+When you are not using your Codespace, you want to be sure to stop it, so you are not using up your hours. See [Stopping and starting a codespace](https://docs.github.com/en/codespaces/developing-in-a-codespace/stopping-and-starting-a-codespace) for more methods to do this.
+
+## A note on "billing"
+
+Free, personal GitHub accounts have 120 core-hours per month of Codespaces usage.
+
+In order to build the devopsdays-web site, you will need a "machine type" of 4 cores and 16 GB of RAM. So this means you can use the Codespace for 30 hours per month. If you are using the Codespace for other projects, you will need to be mindful of your usage.
+
+If you'd like to see how much of your allocated core-hours you have used, visit your [GitHub Billing Summary](https://github.com/settings/billing/summary)